创建商家券

更新时间：2024.11.18

商户可以通过该接口创建商家券。微信支付生成商家券批次后并返回商家券批次号给到商户，商户可调用发券接口【小程序发券】、【H5发券】发放该批次商家券。
频率限制：接口级限制1000/min

接口说明

支持商户：【普通服务商】　【渠道商】

请求方式：【POST】/v3/marketing/busifavor/stocks

请求域名：【主域名】https://api.mch.weixin.qq.com 使用该域名将访问就近的接入点

　　　　　【备域名】https://api2.mch.weixin.qq.com 使用该域名将访问异地的接入点，指引点击查看

请求参数

Header HTTP头参数

Authorization 　必填　string

请参考签名认证生成认证信息

Accept 　必填　string

请设置为application/json

Content-Type 　必填　string

请设置为application/json

body 包体参数

stock_name 　必填 string(21)

【商家券批次名称】批次名称，字数上限为21个，一个中文汉字/英文字母/数字均占用一个字数。

belong_merchant 　必填 string(15)

【批次归属商户号】批次归属于哪个商户。
注：
普通直连模式，该参数为直连商户号；
服务商模式，该参数为子商户号；
间连模式，该参数为子商户号。

comment 　选填 string(20)

【批次备注】仅配置商户可见，用于自定义信息。字数上限为20个，一个中文汉字/英文字母/数字均占用一个字数。

goods_name 　必填 string(15)

【适用商品范围】用来描述批次在哪些商品可用，会显示在微信卡包中。字数上限为15个，一个中文汉字/英文字母/数字均占用一个字数。

stock_type 　必填 string

【批次类型】批次类型

可选取值：

NORMAL: 固定面额满减券批次
DISCOUNT: 折扣券批次
EXCHANGE: 换购券批次

coupon_use_rule 　必填 object

【核销规则】券核销相关规则

属性

coupon_available_time 　必填 object

【券可核销时间】日期区间内可以使用优惠

属性

available_begin_time 　必填 string

【开始时间】批次开始时间，遵循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秒。
注意：商家券有效期最长为1年。

available_end_time 　必填 string

【结束时间】批次结束时间，遵循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秒。
注意：商家券有效期最长为1年。

available_day_after_receive 　选填 integer

【生效后N天内有效】日期区间内，券生效后x天内有效。例如生效当天内有效填1，生效后2天内有效填2，以此类推……注意，用户在有效期开始前领取商家券，则从有效期第1天开始计算天数，用户在有效期内领取商家券，则从领取当天开始计算天数，无论用户何时领取商家券，商家券在活动有效期结束后均不可用。可配合wait_days_after_receive一同填写，也可单独填写。单独填写时，有效期内领券后立即生效，生效后x天内有效。

available_week 　选填 object

【固定周期有效时间段】可以设置多个星期下的多个可用时间段，比如每周二10点到18点

属性

irregulary_avaliable_time 　选填 array[object]

【无规律的有效时间段】无规律的有效时间，多个无规律时间段

属性

wait_days_after_receive 　选填 integer

【领取后N天开始生效】日期区间内，用户领券后需等待x天开始生效。例如领券后当天开始生效则无需填写，领券后第2天开始生效填1，以此类推……用户在有效期开始前领取商家券，则从有效期第1天开始计算天数，用户在有效期内领取商家券，则从领取当天开始计算天数。无论用户何时领取商家券，商家券在活动有效期结束后均不可用。需配合available_day_after_receive一同填写，不可单独填写。注：最大不能超过30天

fixed_normal_coupon 　选填 object

【固定面额满减券使用规则】固定面额满减，折扣券，换购券使用规则三选一，stock_type为NORMAL时必填。

属性

discount_coupon 　选填 object

【折扣券使用规则】固定面额满减，折扣券，换购券使用规则三选一，stock_type为DISCOUNT时必填。

属性

exchange_coupon 　选填 object

【换购券使用规则】固定面额满减，折扣券，换购券使用规则三选一，stock_type为EXCHANGE时必填。

属性

use_method 　必填 string

【核销方式】核销方式

可选取值：

OFF_LINE: 线下滴码核销，点击券“立即使用”跳转展示券二维码详情。
MINI_PROGRAMS: 线上小程序核销，点击券“立即使用”跳转至配置的商家小程序（需要添加小程序AppID和path）。
SELF_CONSUME: 用户自助核销，点击券“立即使用”跳转至用户自助操作核销界面（当前暂不支持用户自助核销）。
PAYMENT_CODE: 微信支付付款码核销，点击券“立即使用”跳转至微信支付钱包付款码。

mini_programs_appid 　选填 string

【小程序AppID】核销方式为线上小程序核销才有效

mini_programs_path 　选填 string

【小程序path】核销方式为线上小程序核销才有效

stock_send_rule 　必填 object

【发放规则】券发放相关规则

属性

out_request_no 　必填 string(128)

【商户请求单号】商户创建批次凭据号（格式：商户ID+日期+流水号），商户侧需保持唯一性

custom_entrance 　选填 object

【自定义入口】卡详情页面，可选择多种入口引导用户

属性

mini_programs_info 　选填 object

【小程序入口】需要小程序APPID、path、入口文案、引导文案。如果需要跳转小程序，APPID、path、入口文案为必填，引导文案非必填。
AppID要与归属商户号有M-A or M-m-suba关系。
注：请查看绑定关系说明文档

属性

appid 　选填 string

【商户公众号AppID】可配置商户公众号，从券详情可跳转至公众号，用户自定义字段。
校验规则：传入的AppID得是与调用方商户号（即请求头里面的商户号）有绑定关系的AppID 或传入的AppID得是归属商户号有绑定关系的AppID

hall_id 　选填 string

【更多优惠入口；营销馆创建地址：https://pay.weixin.qq.com/index.php/xphp/cfav_market/hall#/pages/list/list】填写微信支付营销馆的馆ID，用户自定义字段。营销馆需在商户平台创建。

store_id 　选填 string

【可用门店ID】填写代金券可用门店ID

code_display_mode 　选填 string

【code展示模式】code展示模式

可选取值：

NOT_SHOW: 不展示code
BARCODE: 一维码
QRCODE: 二维码

display_pattern_info 　选填 object

【样式信息】创建批次时的样式信息。

属性

description 　选填 string(1000)

【使用须知】用于说明详细的活动规则，会展示在代金券详情页。

merchant_logo_url 　选填 string

【商户logo】若券归属商户号有认证品牌，则系统将自动拉取对应品牌logo；若券归属商户号不在认证品牌下，需自定义上传logo，未上传时将展示兜底灰色logo样式，影响券详情页用户体验，请及时上传。

商户logo的URL地址，仅支持通过《图片上传API》接口获取的图片URL地址。

1、商户logo大小需为120像素*120像素。

2、支持JPG/JPEG/PNG格式，且图片小于1M。

注：该字段暂不支持修改

merchant_name 　选填 string(16)

【商户名称】不支持商户自定义。若券归属商户号有认证品牌，系统将自动拉取认证品牌号下的品牌名称；若券归属商户号不在认证品牌下，则拉取本商户号的商户简称。展示上限12个字符。
注：该字段暂不支持修改

background_color 　选填 string

【背景颜色】券的背景颜色，可设置10种颜色，色值请参考下方说明。颜色取值为颜色图中的颜色名称。

coupon_image_url 　选填 string

【券详情图片】券详情图片，1074像素（宽）*603像素（高），图片大小不超过2M，支持JPG/PNG格式。仅支持通过《图片上传API》接口获取的图片URL地址。*

finder_info 　选填 object

【视频号相关信息】视频号相关信息

属性

coupon_code_mode 　必填 string

【券code模式】特殊规则：
1、券code模式为WECHATPAY_MODE时，是微信自动分配券code，商户不需要预存code；适用于多种场景
2、券code模式为MERCHANT_API时，无需调用上传预存code接口，调用发券接口时需指定券code；更多用在商家自有流量场景（例如：商家自有小程序、H5网页等）
3、券code模式为MERCHANT_UPLOAD，需要调用上传预存code接口上传code，调用发券接口时无需指定code；更多适用在微信支付平台流量场景（例如：支付有礼、支付有优惠等）

可选取值：

WECHATPAY_MODE: 系统分配code，商户无需额外操作
MERCHANT_API: 商户发放时接口指定券code
MERCHANT_UPLOAD: 商户上传自定义code，发券时系统随机选取上传的券code

notify_config 　选填 object

【事件通知配置】事件回调通知商户的配置

属性

subsidy 　选填 boolean

【是否允许营销补差】该批次发放的券是否允许进行补差，默认为false
注：该字段暂未开放

请求示例

POST

1curl -X POST \
2  https://api.mch.weixin.qq.com/v3/marketing/busifavor/stocks \
3  -H "Authorization: WECHATPAY2-SHA256-RSA2048 mchid=\"1900000001\",..." \
4  -H "Accept: application/json" \
5  -H "Content-Type: application/json" \
6  -d '{
7    "stock_name" : "8月1日活动券",
8    "belong_merchant" : "10000098",
9    "comment" : "活动使用",
10    "goods_name" : "填写商家券可适用的商品或服务",
11    "stock_type" : "NORMAL",
12    "coupon_use_rule" : {
13      "coupon_available_time" : {
14        "available_begin_time" : "2015-05-20T13:29:35+08:00",
15        "available_end_time" : "2015-05-20T13:29:35+08:00",
16        "available_day_after_receive" : 3,
17        "available_week" : {
18          "week_day" : [
19            1
20          ],
21          "available_day_time" : [
22            {
23              "begin_time" : 3600,
24              "end_time" : 86399
25            }
26          ]
27        },
28        "irregulary_avaliable_time" : [
29          {
30            "begin_time" : "2015-05-20T13:29:35+08:00",
31            "end_time" : "2015-05-20T13:29:35+08:00"
32          }
33        ],
34        "wait_days_after_receive" : 7
35      },
36      "fixed_normal_coupon" : {
37        "discount_amount" : 5,
38        "transaction_minimum" : 100
39      },
40      "discount_coupon" : {
41        "discount_percent" : 88,
42        "transaction_minimum" : 100
43      },
44      "exchange_coupon" : {
45        "exchange_price" : 100,
46        "transaction_minimum" : 100
47      },
48      "use_method" : "OFF_LINE",
49      "mini_programs_appid" : "wx23232232323",
50      "mini_programs_path" : "/path/index/index"
51    },
52    "stock_send_rule" : {
53      "max_amount" : 100000,
54      "max_coupons" : 100,
55      "max_coupons_per_user" : 5,
56      "max_amount_by_day" : 1000,
57      "max_coupons_by_day" : 100,
58      "natural_person_limit" : false,
59      "prevent_api_abuse" : false,
60      "transferable" : false,
61      "shareable" : false
62    },
63    "out_request_no" : "100002322019090134234sfdf",
64    "custom_entrance" : {
65      "mini_programs_info" : {
66        "mini_programs_appid" : "wx234545656765876",
67        "mini_programs_path" : "/path/index/index",
68        "entrance_words" : "欢迎选购",
69        "guiding_words" : "获取更多优惠"
70      },
71      "appid" : "wx324345hgfhfghfg",
72      "hall_id" : "233455656",
73      "store_id" : "233554655",
74      "code_display_mode" : "NOT_SHOW"
75    },
76    "display_pattern_info" : {
77      "description" : "xxx门店可用",
78      "merchant_logo_url" : "https://xxx",
79      "merchant_name" : "微信支付",
80      "background_color" : "xxxxx",
81      "coupon_image_url" : "图片cdn地址",
82      "finder_info" : {
83        "finder_id" : "sph6Rngt2T4RlUf",
84        "finder_video_id" : "export/UzFfAgtgekIEAQAAAAAAb4MgnPInmAAAAAstQy6ubaLX4KHWvLEZgBPEwIEgVnk9HIP-zNPgMJofG6tpdGPJNg_ojtEjoT94",
85        "finder_video_cover_image_url" : "https://wxpaylogo.qpic.cn/xxx"
86      }
87    },
88    "coupon_code_mode" : "WECHATPAY_MODE",
89    "notify_config" : {
90      "notify_appid" : "wx23232232323"
91    },
92    "subsidy" : false
93  }'
94

应答参数

200 OK

stock_id 　必填 string

【批次号】批次号

create_time 　必填 string

【创建时间】创建时间，遵循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秒。

应答示例

200 OK

1{
2  "stock_id" : "98065001",
3  "create_time" : "2015-05-20T13:29:35+08:00"
4}
5

错误码

公共错误码

状态码	错误码	描述	解决方案
400	PARAM_ERROR	参数错误	请根据错误提示正确传入参数
400	INVALID_REQUEST	HTTP 请求不符合微信支付 APIv3 接口规则	请参阅接口规则
401	SIGN_ERROR	验证不通过	请参阅签名常见问题
500	SYSTEM_ERROR	系统异常，请稍后重试	请稍后重试

业务错误码

状态码	错误码	描述	解决方案
400	APPID_MCHID_NOT_MATCH	AppID与请求方商户无关联关系	AppID与请求方商户不匹配，请确认AppID与请求方商户是否有关联关系
400	INVALID_REQUEST	发券模式不合法	请更换支持预上传code的批次后重试
400	MCH_NOT_EXISTS	商户号不存在	请确认传入的商户号是否正确
400	RESOURCE_ALREADY_EXISTS	批次已存在	查看out_request_no字段是否重复使用
400	RESOURCE_ALREADY_EXISTS	券已被其他订单核销	请通过查询券API确认券是否已被其他订单核销
400	SYSTEM_ERROR	系统错误	请使用相同参数稍后重新调用
403	NO_AUTH	无权限	查看具体错误信息，确认是否有权限
403	RULE_LIMIT	券不在有效期内	请确认券是否能在当前时间核销
404	RESOURCE_NOT_EXISTS	查询的资源不存在	请检查查询资源的对应ID是否填写正确
404	USER_NOT_EXISTS	OpenID不正确	请确认传入的OpenID是否正确
429	FREQUENCY_LIMITED	频率限制	调用太频繁，请降低调用接口频率
500	SYSTEM_ERROR	系统失败	多为网络超时引起，重试

文档是否有帮助

更多支持

开发文档(商户)开发文档(V2版)开发者社区微信开放平台微信公众平台腾讯客服