最新更新时间:2021.12.20 版本说明
商户可以通过该接口创建商家券。微信支付生成商家券批次后并返回商家券批次号给到商户,商户可调用发券接口【小程序发券】、【H5发券】发放该批次商家券。
商家券满减券预算控制从“金额”调整为“个数”周知
为更好的方便开发者创建管理商家券的满减券,微信支付将对满减券发放预算库存控制进行优化调整,即 从“总预算(单位元)”调整为“最大发放个数(单位个)” 具体如下:
调整前:
满减券(券类型为NORMAL)
参数名 | 变量 | 类型 | 必填 | 描述 |
---|---|---|---|---|
批次总预算 | max_amount | int | 是 | 总预算金额,单位:分。 |
批次最大发放个数 | max_coupons | int | 否 | 特殊规则:取值范围 1 ≤ value ≤ 1000000000 |
单天发放上限金额 | max_amount_by_day | int | 否 | 单天发放上限金额,单位:分(stock_type为NORMAL时可传入此字段控制单天发放上限)。 |
单天发放上限个数 | max_coupons_by_day | int | 否 | 特殊规则:取值范围 1 ≤ value ≤ 1000000000 |
满减券最大可发放个数 = (批次总预算 max_amount)/ (优惠金额 discount_amount)
调整后:
满减券(券类型为NORMAL)
参数名 | 变量 | 类型 | 必填 | 描述 |
---|---|---|---|---|
批次总预算 | max_amount | int | 是 | 总预算金额,单位:分。 |
批次最大发放个数 | max_coupons | int | 是 | 特殊规则:取值范围 1 ≤ value ≤ 1000000000 |
单天发放上限金额 | max_amount_by_day | int | 否 | 单天发放上限金额,单位:分(stock_type为NORMAL时可传入此字段控制单天发放上限)。 |
单天发放上限个数 | max_coupons_by_day | int | 否 | 特殊规则:取值范围 1 ≤ value ≤ 1000000000 |
满减券最大可发放个数 = 批次最大发放个数 max_coupons
策略正式上线时间: 2020/11/2 中午12点
1)策略上线后,仅支持满减券传入max_coupons(批次最大发放个数)与max_coupons_by_day(单天发放上限个数)
2)原金额类控制字段:max_amount(批次总预算)与max_amount_by_day(单天发放上限金额)将不再生效;
3)策略仅对11/2中午2点上线后的新创建批次生效,在此时间点前创建的存量满减券批次不受影响。
策略灰度时间:2020/10/15 18:00:00 至 2020/11/2 11:59:59
在灰度期间,会做预算控制字段做兼容处理,即在此期间新创建的批次:
1)如满减券同时传入“max_amount(批次总预算)”与“max_coupons(批次最大发放个数)”时,则用“max_coupons(批次最大发放个数)”做满减券实际可发放库存控制;
2)如满减券仅传入“max_amount(批次总预算)”,则用“max_amount(批次总预算)”来做发放实际可发放库存控制;(即最大可发放个数 = (批次总预算 max_amount)/ (优惠金额 discount_amount))
3)如满减券单天发放控制同时传入“max_amount_by_day(单天发放上限金额)”与“max_coupons_by_day(单天发放上限个数)”,则使用“max_coupons_by_day(单天发放上限个数)”做满减券单天发放库存控制;
4)如满减券单天发放控制仅传入“max_amount_by_day(单天发放上限金额)”,则使用“max_amount_by_day(单天发放上限金额)”做满减券单天发放库存控制;(即单天最大可发放个数=(单天发放上限金额max_amount_by_day)/ (优惠金额 discount_amount))
新策略上线后,为确保存量批次正常使用,批次查询接口保留返回max_amount(批次总预算)与max_amount_by_day(单天发放上限金额)字段返回。
说明:折扣券与换购券不做调整, 依然保持为
折扣券&换购券最大可发放个数 = 批次最大发放个数 max_coupons
适用对象: 服务商
请求URL:https://api.mch.weixin.qq.com/v3/marketing/busifavor/stocks
请求方式:POST
path 指该参数为路径参数
query 指该参数需在请求URL传参
body 指该参数需在请求JSON传参
参数名 | 变量 | 类型[长度限制] | 必填 | 描述 |
---|---|---|---|---|
商家券批次名称 | stock_name | string[1,21] | 是 | body 批次名称,字数上限为21个,一个中文汉字/英文字母/数字均占用一个字数。 示例值:8月1日活动券 |
批次归属商户号 | belong_merchant | string[8,15] | 是 | body 批次归属于哪个商户。 注: 服务商模式,该参数为子商户号; 间连模式,该参数为子商户号。 示例值:10000022 |
批次备注 | comment | string[1,20] | 否 | body 仅配置商户可见,用于自定义信息。字数上限为20个,一个中文汉字/英文字母/数字均占用一个字数。 示例值:活动使用 |
适用商品范围 | goods_name | string[1,15] | 是 | body 用来描述批次在哪些商品可用,会显示在微信卡包中。字数上限为15个,一个中文汉字/英文字母/数字均占用一个字数。 示例值:xxx商品使用 |
批次类型 | stock_type | string[1,32] | 是 | body 批次类型 NORMAL:固定面额满减券批次 DISCOUNT:折扣券批次 EXCHANGE:换购券批次 示例值:NORMAL |
+核销规则 | coupon_use_rule | object | 是 | body 券核销相关规则 |
+发放规则 | stock_send_rule | object | 是 | body 券发放相关规则 |
商户请求单号 | out_request_no | string[1,128] | 是 | body 商户创建批次凭据号(格式:商户id+日期+流水号),商户侧需保持唯一性。 示例值:100002322019090134234sfdf |
+自定义入口 | custom_entrance | object | 否 | body 卡详情页面,可选择多种入口引导用户。 |
+样式信息 | display_pattern_info | object | 否 | body 创建批次时的样式信息。 |
券code模式 | coupon_code_mode | string[1,128] | 是 | body 枚举值: WECHATPAY_MODE:系统分配券code。(固定22位纯数字) MERCHANT_API:商户发放时接口指定券code。 MERCHANT_UPLOAD:商户上传自定义code,发券时系统随机选取上传的券code。 特殊规则: 1、券code模式为WECHATPAY_MODE时,是微信自动分配券code,商户不需要预存code;适用于多种场景 2、券code模式为MERCHANT_API时,无需调用上传预存code接口,调用发券接口时需指定券code;更多用在商家自有流量场景(例如:商家自有小程序、H5网页等) 3、券code模式为MERCHANT_UPLOAD,需要调用上传预存code接口上传code,调用发券接口时无需指定code;更多适用在微信支付平台流量场景(例如:支付有礼、支付有优惠等) 示例值:WECHATPAY_MODE |
+事件通知配置 | notify_config | object | 否 | body 事件回调通知商户的配置。 |
是否允许营销补贴 | subsidy | bool | 否 | body 该批次发放的券是否允许进行补差,默认为false 示例值:false |
卡券背景颜色图
{
"stock_name":"8月1日活动券",
"belong_merchant":"10000098",
"comment": "活动使用",
"goods_name": "XXX商品使用",
"stock_type": "NORMAL",
"coupon_use_rule": {
"coupon_available_time": {
"available_begin_time": "2015-05-20T13:29:35+08:00",
"available_end_time": "2015-05-20T13:29:35+08:00",
"available_day_after_receive": 3,
"wait_days_after_receive":7,
"available_week": {
"week_day": [
1,
2
],
"available_day_time": [
{
"begin_time": 3600,
"end_time": 86399
}
]
},
"irregulary_avaliable_time": [
{
"begin_time": "2015-05-20T13:29:35+08:00",
"end_time": "2015-05-20T13:29:35+08:00"
}
]
},
"fixed_normal_coupon": {
"discount_amount": 5,
"transaction_minimum": 100
},
"use_method": "OFF_LINE",
"mini_programs_appid":"wx23232232323",
"mini_programs_path":"/path/index/index"
},
"stock_send_rule": {
"max_coupons": 100,
"max_coupons_per_user": 5,
"max_coupons_by_day": 100,
"natural_person_limit": false,
"prevent_api_abuse": false,
"transferable": false,
"shareable": false
},
"out_request_no": "100002322019090134234sfdf",
"custom_entrance": {
"mini_programs_info": {
"mini_programs_appid": "wx234545656765876",
"mini_programs_path": "/path/index/index",
"entrance_words": "欢迎选购",
"guiding_words": "获取更多优惠"
},
"appid": "wx324345hgfhfghfg",
"hall_id": "233455656",
"store_id": "233554655"
},
"display_pattern_info": {
"description": "xxx门店可用",
"merchant_logo_url": "https://xxx",
"merchant_name": "微信支付",
"background_color": "Color020",
"coupon_image_url": "https://qpic.cn/xxx",
"finder_info": {
"finder_id": "sph6Rngt2T4RlUf",
"finder_video_cover_image_url": "https://wxpaylogo.qpic.cn/xxx",
"finder_video_id": "export/UzFfAgtgekIEAQAAAAAAb4MgnPInmAAAAAstQy6ubaLX4KHWvLEZgBPEwIEgVnk9HIP-zNPgMJofG6tpdGPJNg_ojtEjoT94"
}
},
"coupon_code_mode": "WECHATPAY_MODE"
}
参数名 | 变量 | 类型[长度限制] | 必填 | 描述 |
---|---|---|---|---|
批次号 | stock_id | string[1,20] | 是 | 微信为每个商家券批次分配的唯一ID。 示例值:98065001 |
创建时间 | create_time | string[1,32] | 是 | 创建时间,遵循rfc3339标准格式,格式为yyyy-MM-DDTHH:mm:ss+TIMEZONE,yyyy-MM-DD表示年月日,T出现在字符串中,表示time元素的开头,HH:mm:ss表示时分秒,TIMEZONE表示时区(+08:00表示东八区时间,领先UTC 8小时,即北京时间)。例如:2015-05-20T13:29:35.+08:00表示,北京时间2015年5月20日 13点29分35秒。 示例值:2015-05-20T13:29:35+08:00 |
{
"stock_id": "98065001",
"create_time": "2015-05-20T13:29:35+08:00"
}
如果商家券配置了跳转小程序的入口(包括立即使用以及自定义入口),跳转链接会带有批次号、openid以及加密的code,解密方式可参考解密说明。
/path/index/index.html?stock_id=128695000000007&openid=o7tgX0RiTlJo9IXVVfemjFSlFMo4&nonce=B9Jr9gtzMSs7&associate=COUPON_CODE&ciphertext=nmARA5zbjlL%2FaCiKN7S3h1z%2FGhmCfNW9IGQHX6XqTR3zYzQ43sQ%3D
状态码 | 错误码 | 描述 | 解决方案 |
---|---|---|---|
400 | PARAM_ERROR | 参数错误 | 查看具体错误信息,调整参数 |
400 | SYSTEM_ERROR | 系统错误 | 请使用相同参数稍后重新调用 |
400 | RESOURCE_ALREADY_EXISTS | 批次已存在 | 查看out_request_no字段是否重复使用 |
券已被其他订单核销 | 请通过查询券API确认券是否已被其他订单核销 | ||
404 | RESOURCE_NOT_EXISTS | 查询的资源不存在 | 请检查查询资源的对应id是否填写正确 |
403 | NOAUTH | 无权限 | 查看具体错误信息,确认是否有权限 |
400 | APPID_MCHID_NOT_MATCH | appid与请求方商户无关联关系 | appid与请求方商户不匹配,请确认appid与请求方商户是否有关联关系 |
400 | MCH_NOT_EXISTS | 商户号不存在 | 请确认传入的商户号是否正确 |
404 | USER_NOT_EXISTS | openid不正确 | 请确认传入的openid是否正确 |
500 | SYSTEM_ERROR | 系统失败 | 多为网络超时引起,重试 |
429 | FREQUENCY_LIMITED | 频率限制 | 调用太频繁,请降低调用接口频率 |
403 | RULELIMIT | 券不在有效期 | 请确认券是否能在当前时间核销 |
400 | INVALID_REQUEST | 发券模式不合法 | 请更换支持预上传code的批次后重试 |
上传的自定义code已达上限 | 请更换一个新的批次后重试 |