# 添加非卖赠品

调试诊断

接口应在服务器端调用,不可在前端(小程序、网页、APP等)直接调用,具体可参考接口调用指南

接口英文名:addgiftproduct

通过该接口可添加非卖赠品

# 1. 调用方式

# HTTPS 调用

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

# 云调用

  • 本接口不支持云调用

# 第三方调用

  • 本接口支持第三方平台代微信小店商家调用。

  • 该接口所属的权限集 id 为:129

  • 服务商获得其中之一权限集授权后,可通过使用 authorizer_access_token 代微信小店商家进行调用,具体可查看 第三方调用 说明文档。

# 2. 请求参数

# 查询参数 Query String parameters

参数名类型必填示例说明
access_tokenstringACCESS_TOKEN接口调用凭证,可使用 access_token(微信小店商家)、authorizer_access_token(服务商)

# 请求体 Request Payload

参数名类型必填说明
out_product_idstring外部平台自定义赠品ID,小店后台不作任何唯一性约束,开发者自行保证,一旦添加成功后该字段无法修改,最多128字符
titlestring标题,应至少含5个有效字符数(中文文字/英文字母/数字,都各算1个有效字符数,且不得仅为数字或英文,不得含非法字符,允许的特殊字符集为:`·~~!@#$%^&()!@#¥%……&*()-_——=+[]\【】、{} \||;';’:": ‘“”,./,。、<>?《》?\u00A0\u0020\u3000),最多60字符。
head_imgsarray主图,多张,列表,最少3张(食品饮料和生鲜类目赠品最少4张),最多9张。不得有重复图片。无形状尺寸要求,最终在商详页会显示为正方形
desc_infoobjectdesc_info
cats_v2objarray赠品类目,新类目树结构
attrsobjarray赠品参数,部分类目有必填的参数,具体参考文档获取类目信息中的字段attr.product_attr_list[].is_required
spu_codestring商家自定义的赠品编码
brand_idstring(uint64)品牌id,无品牌为“2100000000”
skusobjarray仅支持单sku,长度固定为1
listingnumber添加完成后是否立即上架。1:是;0:否;默认0

# Body.desc_info Object Payload

desc_info

参数名类型必填说明
imgsarray赠品详情图片(最少1张,最多20张。其中食品饮料和生鲜类目赠品最少3张)。不得有重复图片
descstring赠品详情文本

# Body.cats_v2(Array) Object Payload

赠品类目,新类目树结构

参数名类型必填说明
cat_idstring类目ID,需要先通过获取类目接口拿到可用的cat_id;这里的cat_id顺序与一,二,三,...,N 级类目严格一致,即数组下标为 0 的是一级类目,数组下标为 1 的是二级类目,数组下标 length - 1 的是 N 级类目(即最后一级叶子类目)

# Body.attrs(Array) Object Payload

赠品参数,部分类目有必填的参数,具体参考文档获取类目信息中的字段attr.product_attr_list[].is_required

参数名类型必填说明
attr_keystring属性键key(属性自定义用)
attr_valuestring属性值(属性自定义用)。如果添加时没录入,回包可能不包含该字段,参数规则如下: ● 当获取类目信息接口中返回的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 的格式:字符串形式的数字

# Body.skus(Array) Object Payload

仅支持单sku,长度固定为1

参数名类型必填说明
out_sku_idstring外部平台自定义sku_id,小店后台不作任何唯一性约束,开发者自行保证,一旦添加成功后该字段无法修改,最多128字符
sale_pricenumber售卖价格,以分为单位,不超过1000000000(1000万元)
stock_numnumber创建赠品初始化设置的库存
sku_codestring商家自定义的sku编码,最多100字符

# 3. 返回参数

# 返回体 Response Payload

参数名类型说明
errcodenumber错误码
errmsgstring错误信息
product_idstring(uint64)赠品ID
create_timestring创建时间

# 4. 注意事项

  • 本接口添加的赠品为非卖赠品,不会与线上赠品产生关联。如需添加在售赠品,请使用设置在售赠品接口。

  • 非卖赠品有2份数据,草稿和线上数据,调用接口新增和修改赠品数据后,影响的只是草稿数据,要调上架接口,并审核通过,草稿数据才会覆盖线上数据正式生效。

  • 赠品目前仅支持单sku。

  • 在上传完成之前调用上架商品接口,会返回10020067,因此如果有更新赠品并提交审核的需求,建议直接在本接口将listing参数设置为1,不需要再调用上架赠品的接口。

  • 图片相关参数(如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/),则可以直接提交。

  • 赠品无需设置发货方式,发货方式跟随主品。

# 5. 代码示例

请求示例

{
    "title": "宠物玩具5",
    "head_imgs": [
        "https://mmecimage.cn/p/wx37f38d59298839c3/HJE9eJaEc5bJk-eaArVdILSB7MMaHgdK2-JIn51nMQ"
    ],
    "desc_info": {
        "imgs": [
            "https://mmecimage.cn/p/wx37f38d59298839c3/HJE9eJaEc5bJk-eaArVdILSB7MMaHgdK2-JIn51nMQ"
        ],
        "desc": "物美价廉"
    },
    "cats_v2": [
        {
            "cat_id": "10000026"
        },
        {
            "cat_id": "10000032"
        },
        {
            "cat_id": "1246"
        }
    ],
    "attrs": [
        {
            "attr_key": "产品净重(kg)",
            "attr_value": "1"
        }
    ],
    "skus": [
        {
            "sale_price": 100,
            "stock_num": 0
        }
    ],
    "spu_code": "SPU_CODE_XXX",
    "brand_id": "2100000000"
}

返回示例

{
	"errcode": 0,
	"errmsg": "ok",
	"data": {
		"product_id": "1700000000000",
		"create_time": "2020-03-25 12:05:25"
	}
}

# 6. 错误码

以下是本接口的错误码列表,其他错误码可参考 通用错误码

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

# 7. 适用范围

本接口支持「微信小店」账号类型调用。其他账号类型如无特殊说明,均不可调用。