# 更新商品

# 接口说明

该接口用于对视频号小店内商品信息的更新

# 注意事项

  • 商品有2份数据,草稿和线上数据,调用接口新增和修改商品数据后,影响的只是草稿数据,要调用上架商品接口(或本接口参数listing设置为1),并审核通过,草稿数据才会覆盖线上数据正式生效;

  • 商品sku数量超过25个的情况下,接口会异步更新商品信息。在上传完成之前调用上架商品接口,会返回10020067,因此如果有更新商品并提交审核的需求,建议直接在本接口将listing参数设置为1,不需要再调用上架商品的接口;

  • 该接口请求方式和添加商品接口基本一致,区别在于请求该接口时需要带上已存在的product_id;

  • 该接口是覆盖写操作,每次提交后,草稿数据会被整体替换为本次请求上传的数据:

    1. 若sku列表中带上已存在的sku_id,则会用新上传的内容更新对应的sku草稿;
    2. 若列表中某个的sku没有传入sku_id,则视为新增的sku,分配新的sku_id并插入到商品草稿中;
    3. 若原本存在于商品信息中的某个sku_id,在本次更新没有上传,则视为删除,商品草稿将移除该sku,在商品审核通过后,以上变动将作用于线上数据。
  • 图片相关参数(如head_img、desc_info.imgs、qualifications、product_qua_infos[].qua_url[]、skus[].thumb_img等),请务必使用接口上传图片(参数resp_type=1),并将返回的img_url填入此处,不接受其他任何格式的图片url。若url曾经做过转换( url前缀为mmecimage.cn/p/),则可以直接提交。

  • 启用新多级类目树提示:旧的类目树固定为三级类目结构,新的类目树为多级类目结构,过渡期间,新旧类目树兼容使用,请开发者尽快切换到新多级类目树。其中差异请参阅“新旧类目树差异”。此接口新增 cats_v2 字段支持新类目树,详见参数。

    • 如果商户设置了 cats_v2 的信息,会优先读取 cats_v2,作为类目信息,说明商户请求使用新的类目结构(多级类目结构)。
    • 如果商户未设置 cats_v2 字段,使用 cats,说明商户请求使用旧的类目结构(三级类目结构)。
    • cats_v2 字段填写类目信息(与 level1 / level2 / levle3 字段同级),顺序与一,二,三,...,N 级类目严格一致,即数组下标为 0 的是一级类目,数组下标为 1 的是二级类目,数组下标 length - 1 的是 N 级类目(即最后一级叶子类目)。

# 接口调用请求说明

POST https://api.weixin.qq.com/channels/ec/product/update?access_token=ACCESS_TOKEN

# 请求参数说明

参数 类型 是否必填 描述
product_id string(uint64) 小店内部商品ID
title string 标题,应至少含5个有效字符数(中文文字/英文字母/数字,都各算1个有效字符数,且不得仅为数字或英文,不得含非法字符,允许的特殊字符集为:`·~~!@#$%^&()!@#¥%……&*()-_——=+[]\【】、{} \||;';’:": ‘“”,./,。、<>?《》?\u00A0\u0020\u3000),最多60字符。

合规商品标题举例:
1.糖醋排骨【预订价10元】;
2.CheddarCheese切达干酪;
3.百岁山天然矿泉水1L*15瓶。
不合规商品标题举例:
1.正宗五指毛桃根√;
2.Classic Whole Wheat;
3.便携式折叠扇第Ⅲ代;
4.iPhone 13;
5.Mac999;
6.[五元]扇子
sub_title string 副标题,最多18字符
head_imgs array[string] 主图,多张,列表,最少3张(食品饮料和生鲜类目商品最少4张),最多9张。不得有重复图片。无形状尺寸要求,最终在商详页会显示为正方形
deliver_method number 发货方式:0-快递发货;1-无需快递,手机号发货;3-无需快递,可选发货账号类型,默认为0,若为无需快递,则无需填写运费模版id
deliver_acct_type array(number) 发货账号:1-微信openid;2-QQ号;3-手机号;4-邮箱。可多选,只有deliver_method=3时,本参数有意义。且当发货账号为微信、QQ和邮箱时,需要更新订单接口读取详情字段,详情参考订单接口的说明。
desc_info.imgs array[string] 商品详情图片(最少1张,最多20张。其中食品饮料和生鲜类目商品最少3张)。不得有重复图片
desc_info.desc string 商品详情文本
cats[] array 商品类目,大小恒等于3(一二三级类目)
cats[].cat_id number 类目ID,需要先通过获取所有类目接口拿到可用的cat_id;这里的cat_id顺序与一,二,三级类目严格一致,即数组下标为0的是一级类目,数组下标为1的是二级类目,数组下标为2的是三级类目。
cats_v2[] array 商品类目,新类目树结构|
cats_v2[].cat_id string(uint64) 类目ID,需要先通过获取类目接口拿到可用的cat_id;这里的cat_id顺序与一,二,三,...,N 级类目严格一致,即数组下标为 0 的是一级类目,数组下标为 1 的是二级类目,数组下标 length - 1 的是 N 级类目(即最后一级叶子类目)|
attrs[] array 商品参数,部分类目有必填的参数,具体参考文档获取类目信息中的字段attr.product_attr_list[].is_required
attrs[].attr_key string 属性键key(属性自定义用)
attrs[].attr_value string 属性值value(属性自定义用)
● 当获取类目信息接口中返回的type:为 select_many,
attr_value的格式:多个选项用分号;隔开
示例:某商品的适用人群属性,选择了:青年、中年,则 attr_value的值为:青年;中年
● 当获取类目信息接口中返回的type:为 integer_unit/decimal4_unit
attr_value格式:数值 单位,用单个空格隔开
示例:某商品的重量属性,要求integer_unit属性类型,数值部分为 18,单位选择为kg,则 attr_value的值为:18 kg
● 当获取类目信息接口中返回的type:为 integer/decimal4
attr_value 的格式:字符串形式的数字
spu_code string 商品编码
brand_id string(uint64) 品牌id,无品牌为“2100000000”
qualifications array[string] 商品资质图片(最多5张)。该字段将被product_qua_infos代替
product_qua_infos[] array 商品资质列表,取代qualifications,具体参考文档获取类目信息中的字段product_qua_list[]
product_qua_infos[].qua_id string(uint64) 商品资质id,对应获取类目信息中的字段product_qua_list[].qua_id
product_qua_infos[].qua_url[] array(string) 商品资质图片列表(单个商品资质id下,最多10张)
express_info.template_id string(uint64) 运费模板ID(先通过获取运费模板列表接口拿到),若deliver_method=1或3,则不用填写
express_info.weight number 商品重量,单位克,若当前运费模版计价方式为[按重量],则必填
aftersale_desc string 售后说明
limited_info.period_type number 限购周期类型,0:无限购(默认),1:按自然日限购,2:按自然周限购,3:按自然月限购,4:按自然年限购
limited_info.limited_buy_num number 限购数量
extra_service.seven_day_return number 是否支持七天无理由退货,0-不支持七天无理由,1-支持七天无理由,2-支持七天无理由(定制商品除外),3-支持七天无理由(使用后不支持)。管理规则请参见七天无理由退货管理规则。类目是否必须支持七天无理由退货,可参考文档获取类目信息中的字段attr.seven_day_return
extra_service.freight_insurance number 是否支持运费险,0-不支持运费险,1-支持运费险。需要商户开通运费险服务,非必须开通运费险类目的商品依据该字段进行设置,必须开通运费险类目中的商品将默认开启运费险保障,不依据该字段。规则详情请参见 视频号小店「运费险」管理规则
extra_service.fake_one_pay_three number 是否支持假一赔三,0-不支持假一赔三,1-支持假一赔三。
extra_service.damage_guarantee number 是否支持坏损包退,0-不支持坏损包退,1-支持坏损包退。
skus[] array 长度最少为1,最大为500
skus[].sku_id string(uint64) 若填了已存在sku_id,则进行更新sku操作,否则新增sku
skus[].out_sku_id string 商家自定义sku_id,小店后台不作任何唯一性约束,开发者自行保证,一旦添加成功后该字段无法修改,最多128字符
skus[].thumb_img string sku小图
skus[].sale_price number 售卖价格,以分为单位,不超过1000000000(1000万元)
skus[].stock_num number 库存
skus[].sku_code string sku编码,最多100字符
skus[].sku_attrs[] array 销售属性,每个spu下面的第一个sku的sku_attr.key顺序决定商品详情页规格名称的排序。部分类目有必填的销售属性,具体参考文档获取类目信息中的字段attr.sale_attr_list[].is_required
skus[].sku_attrs[].attr_key string 属性键key,最终展示为商详页sku规格的名称,如“尺码”、“颜色”,最多40字符
skus[].sku_attrs[].attr_value string 属性值value(属性自定义用)
● 当获取类目信息接口中返回的type:为 select_many,
attr_value的格式:多个选项用分号;隔开
示例:某商品的适用人群属性,选择了:青年、中年,则 attr_value的值为:青年;中年
● 当获取类目信息接口中返回的type:为 integer_unit/decimal4_unit
attr_value格式:数值 单位,用单个空格隔开
示例:某商品的重量属性,要求integer_unit属性类型,数值部分为 18,单位选择为kg,则 attr_value的值为:18 kg
● 当获取类目信息接口中返回的type:为 integer/decimal4
attr_value 的格式:字符串形式的数字
skus[].sku_deliver_info.stock_type number sku库存情况。0:现货(默认),1:全款预售。部分类目支持全款预售,具体参考文档获取类目信息中的字段attr.pre_sale
skus[].sku_deliver_info.full_payment_presale_delivery_type number sku发货节点,该字段仅对stock_type=1有效。0:付款后n天发货,1:预售结束后n天发货
skus[].sku_deliver_info.presale_begin_time number sku预售周期开始时间,秒级时间戳,该字段仅对delivery_type=1有效。
skus[].sku_deliver_info.presale_end_time number sku预售周期结束时间,秒级时间戳,该字段仅对delivery_type=1有效。限制:预售结束时间距离现在<=30天,即presale_end_time - now <= 2592000。预售时间区间<=15天,即presale_end_time - presale_begin_time <= 1296000
skus[].sku_deliver_info.full_payment_presale_delivery_time number sku发货时效,即付款后/预售结束后{full_payment_presale_delivery_time}天内发货,该字段仅对stock_type=1时有效。当发货节点选择“0:付款后n天发货”时,范围是[4, 15]的整数;当发货节点选择“1:预售结束后n天发货”时,范围是[1, 3]的整数
listing number 更新后是否立即上架。1:是;0:否;默认0
after_sale_info.after_sale_address_id number 售后地址id,使用地址管理相关接口进行添加获取
size_chart.enable bool 是否启用尺码表
size_chart.specification_list array 尺码表,启用尺码表时必填
size_chart.specification_list[].name string 尺码属性名称
size_chart.specification_list[].unit string 尺码属性值的单位
size_chart.specification_list[].is_range bool 尺码属性值是否为区间
size_chart.specification_list[].value_list array 尺码值与尺码属性值的映射列表
size_chart.specification_list[].value_list[].key string 尺码值,需与商品属性中的尺码规格保持一致
size_chart.specification_list[].value_list[].value string 尺码属性值;属性值为单值时填写;不能超过5个字符
size_chart.specification_list[].value_list[].left string 尺码属性值的左边界,需小于右边界;属性值为区间时填写;不能超过5个字符
size_chart.specification_list[].value_list[].right string 尺码属性值的右边界,需大于左边界;属性值为区间时填写;不能超过5个字符

# 请求参数示例

{
    "product_id": "10000000089215",
    "title": "任天堂 Nintendo Switch 国行续航增强版 NS家用体感游戏机掌机 便携掌上游戏机 红蓝主机",
    "sub_title": "随时随地,一起趣玩。【更新】",
    "head_imgs": [
        "https://mmecimage.cn/p/wx37f38d59298839c3/HJE9eJaEc5bJk-eaArVdILSB7MMaHgdK2-JIn51nMQ"
    ],
    "desc_info": {
        "imgs": [
            "https://mmecimage.cn/p/wx37f38d59298839c3/HJE9eJaEc5bJk-eaArVdILSB7MMaHgdK2-JIn51nMQ"
        ],
        "desc": "物美价廉"
    },
    "cats": [],
    "cats_v2": [
        {
            "cat_id": "10000111"
        },
        {
            "cat_id": "10000113"
        },
        {
            "cat_id": "6091"
        }
    ],
    "attrs": [
            {
             "attr_key": "产地",
             "attr_value": "四川成都"
            },
            {
             "attr_key": "材质",
             "attr_value": "玻璃"
            },
            {
            "attr_key": "适用人群",
            "attr_value": "青年;中年"
            },
            {
            "attr_key": "数量",
            "attr_value": "33"
            },
            {
            "attr_key": "精度",
            "attr_value": "3.001"
            },
            {
            "attr_key": "重量",
            "attr_value": "38 mg"
            },
            {
           "attr_key": "毛重",
           "attr_value": "380 kg"
            }     
    ],
    "express_info": {
        "template_id": "47428464001"
    },
    "skus": [
        {
            "sku_id": "462966903",
            "thumb_img": "https://mmecimage.cn/p/wx37f38d59298839c3/HJE9eJaEc5bJk-eaArVdILSB7MMaHgdK2-JIn51nMQ",
            "sale_price": 1300,
            "stock_num": 100,
            "sku_code": "A24525252",
            "sku_attrs": [
                    {
                        "attr_key": "产地",
                        "attr_value": "四川成都"
                    },
                    {
                        "attr_key": "材质",
                        "attr_value": "玻璃"
                    },
                    {
                        "attr_key": "适用人群",
                        "attr_value": "青年;中年"
                    },
                    {
                        "attr_key": "数量",
                        "attr_value": "33"
                    },
                    {
                        "attr_key": "精度",
                        "attr_value": "3.001"
                    },
                    {
                         "attr_key": "重量",
                         "attr_value": "38 mg"
                    },
                    {
                         "attr_key": "毛重",
                         "attr_value": "380 kg"
                    } 
            ],
            "sku_deliver_info": {
                "stock_type":0
            }
        },
        {
            "thumb_img": "https://mmecimage.cn/p/wx37f38d59298839c3/HJE9eJaEc5bJk-eaArVdILSB7MMaHgdK2-JIn51nMQ",
            "sale_price": 1000,
            "stock_num": 100,
            "sku_code": "A24525252",
            "sku_attrs": [
                    {
                        "attr_key": "产地",
                        "attr_value": "四川成都"
                    },
                    {
                        "attr_key": "材质",
                        "attr_value": "玻璃"
                    },
                    {
                        "attr_key": "适用人群",
                        "attr_value": "青年;中年"
                    },
                    {
                        "attr_key": "数量",
                        "attr_value": "33"
                    },
                    {
                        "attr_key": "精度",
                        "attr_value": "3.001"
                    },
                    {
                         "attr_key": "重量",
                         "attr_value": "38 mg"
                    },
                    {
                         "attr_key": "毛重",
                         "attr_value": "380 kg"
                    } 
            ],
            "sku_deliver_info": {
                "stock_type":0
            }
        }
    ],
    "product_qua_infos": [
    {
      "qua_id": "1111488",
      "qua_url": [
        "https://mmecimage.cn/p/wx37f38d59298839c3/HJE9eJaEc5bJk-eaArVdILSB7MMaHgdK2-JIn51nMQ",
        "https://mmecimage.cn/p/wx37f38d59298839c3/HJE9eJaEc5bJk-eaArVdILSB7MMaHgdK2-JIn71nCC"
      ]
    },
    {
      "qua_id": "1111489",
      "qua_url": [
        "https://mmecimage.cn/p/wx37f38d59298839c3/HJE9eJaEc5bJk-eaArVdILSB7MMaHgdK2-JIn51nMQ",
        "https://mmecimage.cn/p/wx37f38d59298839c3/HJE9eJaEc5bJk-eaArVdILSB7MMaHgdK2-JIn71nCC"
      ]
    }
  ]
}

# 返回参数说明

参数 类型 描述
errcode number 错误码
errmsg string 错误信息
data.product_id number(uint64) 小店内部商品ID
data.update_time string 更新时间

# 返回参数示例

{
    "errcode": 0,
    "errmsg": "ok",
    "data": {
        "product_id": "23423523452345235",
        "update_time": "2020-06-20 10:00:00"
    }
}

# 错误码

错误码 错误描述
公共错误码 -
10020008 当前商品不允许编辑
10020011 商品的类目长度不对(预期是有三级类目)
10020012 销售属性不合法,不属于商品所属的三级类目
10020013 商品sku数量不合理(sku数量必须在1-500之间)
10020014 该spu处于抢购状态,不能修改sku
10020016 批量添加sku失败
10020017 类目非法
10020018 商家不具备当前类目资质
10020019 运费模版非法
10020020 商品标题为空
10020021 商品标题过长
10020022 商品头图为空
10020023 商品头图过多
10020024 商品描述过长
10020025 商品详情图片过多
10020026 商品详情描述过长
10020027 资质图片过多
10020028 sku价格过高
10020029 sku商品编码过长
10020031 sku销售属性相同key下不能超过100个不同value
10020032 sku销售属性key过长
10020033 sku销售属性value过长
10020034 该商品的sku_id/sku_out_id填写有误
10020035 图片/视频url非法, url前缀应为mmecimage.cn/p/
10020036 out_product_id过长
10020037 out_sku_id过长
10020038 上架的商品缺少sku
10020039 SKU价格为0
10020040 sku售卖价格大于市场价格
10020041 账号注销中
10020042 商品标题过短
10020043 类目不可用,请更换类目
10020045 商品标题不得仅为数字、字母、字符,不得含非法字符,请修改后重新提交
10020046 商品信息设置有误,请重新输入
10020048 由于类目保证金不足,已禁止新增商品
10020049 商品正在审核中,无法编辑或删除,请先调用撤回商品审核接口
10020050 没有商品权限
10020051 参数错误
10020052 商品不存在
10020053 商品因违规已被封禁
10020066 本店铺近1小时内提审次数超过限制,请1小时后再试
10020067 该商品上一次提交正在上传中,请稍后再试
10020068 当前运费模版计价方式为[按重量],且提交商品重量为0
10020069 当前类目不允许选择无需快递的发货方式
10020070 由于类目保证金不足,已下架所有商品
10020083 该商品所需类目保证金高于当前保证金余额,请前往商家网页端添加一次该类目商品,即可完成保证金补缴。
10020088 当前类目不支持当前品牌,或商品品牌id非法,或商品品牌id未申请通过
10020089 未开张商店发布商品
10020091 不支持该类型的商品
10020095 售后说明超过长度限制(200 UTF字符)
10020096 商品参数名称attrs[].attr_key不能重复
10020097 当前类目的商品参数attrs缺少必填项,具体参考文档获取类目信息中的字段attr.product_attr_list[]
10020098 当前类目的商品参数attrs[].attr_value内容有误,具体参考文档获取类目信息中的字段attr.product_attr_list[]
10020099 预售时间为0
10020100 预售开始时间大于等于结束时间
10020101 预售时间区间超出类目限制范围
10020102 预售结束时间距离现在大于30天
10020125 预售开始时间距离现在大于3天
10020103 预售发货预计时间超出类目限制范围
10020104 当前类目不支持预售,具体参考文档获取类目信息中的字段attr.pre_sale
10020106 请上传至少3张商品头图
10020107 请上传至少1张商品详情图
10020108 当前类目必须支持七天无理由退货,extra_service.seven_day_return必须为1或者2
10020109 商品所属类目与主营类目不符,不支持上架
10020110 商品信息检查不通过
10020111 本店铺近1天内提审次数超过限制,请1天后再试
10020113 商品参数属性值为空,请检查后重新提交
10020208 本店铺的上架功能被封禁,请登录视频号小店后台管理页查看详情
10020209 传入的skuid不属于当前商品
10020210 限购库存不能为0
10020211 当前店铺因为有未缴纳欠费,无法上架商品,请登录视频号小店后台管理页查看详情
10020212 商品副标题不得仅为数字、字母、字符,不得含非法字符,请修改后重新提交
10020213 商品详情描述不得仅为数字、字母、字符,不得含非法字符,请修改后重新提交
10020214 商品售后说明不得仅为数字、字母、字符,不得含非法字符,请修改后重新提交
10020215 当前类目不支持该品牌
10020216 商品sku销售参数skus[].sku_attrs缺少必填项,具体参考文档获取类目信息中的字段attr.sale_attr_list[]
10020221 根据《视频号小店「运费险」管理规则》旗舰店类型小店需开通运费险服务方可上架商品,请使用网页端登录并开通
10020222 根据《视频号小店「运费险」管理规则》近7天退货率高于10%或商责纠纷率大于0.08%店铺需完成运费险开通签约方可上架商品,请使用网页端登录并开通
10020225 商品头图重复
10020226 商品详情图重复
10020228 商品头图与其他商品重复
10020229 请上传至少4张商品头图
10020230 请上传至少3张商品详情图
10020231 根据《视频号小店「运费险」管理规则》,预售功能需开通运费险功能后才可打开,当前暂未开通,请至网页端开通运费险功能后重新尝试
10020234 根据《视频号小店「运费险」管理规则》,旗舰店/服务违规小店/退货退款率较高小店需开通运费险服务方可上架商品,请使用网页端登录并开通运费险
10020235 当前店铺包含需要质检服务的类目资质,无法经营和上架其他非质检类目商品。具体可参考相关条款