创建代金券批次

更新时间：2024.11.18

商户可以通过调用此接口创建微信支付代金券批次，包括预充值&免充值代金券；创建完成后将获得代金券批次id，将可用于各个营销场景的活动投放。

接口频率：单个商户号调用频率60/min，所有商户号调用频率为1000/min

接口耗时：500ms

接口说明

支持商户：【普通服务商】　【从业机构（银行）】　【从业机构（支付机构）】　【渠道商】　【清算机构】

请求方式：【POST】/v3/marketing/favor/coupon-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(20)

【批次名称】批次名称
校验规则：
1、批次名称最多9个中文汉字
2、批次名称最多20个字母
3、批次名称中不能包含不当内容和特殊字符 _ , ; |

comment 　选填 string(60)

【批次备注】仅配置商户可见，用于自定义信息

belong_merchant 　必填 string(20)

【归属商户号】批次归属商户号
本字段暂未开放生效，但入参时请设置为当前创建代金券商户号即不会报错，暂时不支持入参其他的商户号

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、开始时间不可早于当前时间
2、不能创建365天后开始的批次
3、批次可用时间范围最长为90天

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秒。

stock_use_rule 　必填 object

【发放规则】批次使用规则

属性

pattern_info 　选填 object

【代金券详情页】代金券详情页

属性

description 　必填 string(1000)

【使用说明】用于说明详细的活动规则，会展示在代金券详情页。
校验规则：最多1000个UTF8字符

merchant_logo 　选填 string(128)

【商户logo】商户logo，仅支持通过《图片上传API》接口获取的图片URL地址。1、商户logo大小需为120像素*120像素。2、支持JPG/JPEG/PNG格式，且图片小于1M。3、最多128个UTF8字符

merchant_name 　选填 string(12)

【品牌名称】品牌名称，展示在用户卡包
校验规则：
1、最多12个中文汉字
2、最多36个英文字符

background_color 　选填 string

【背景颜色】券的背景颜色，可设置14种颜色，色值请参考下方说明。颜色取值为颜色图中的颜色名称。可选枚举字段不用则不传，不可以传空值

可选取值：

COLOR010: 色值 #63b359

COLOR020: 色值 #2c9f67

COLOR030: 色值 #509fc9

COLOR040: 色值 #5885cf

COLOR050: 色值 #9062c0

COLOR060: 色值 #d09a45

COLOR070: 色值 #e4b138

COLOR080: 色值 #ee903c

COLOR081: 色值 #f08500

COLOR082: 色值 #a9d92d

COLOR090: 色值 #dd6549

COLOR100: 色值 #cc463d

COLOR101: 色值 #cf3e36

COLOR102: 色值 #5E6671

coupon_image 　选填 string(128)

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

jump_target 　选填 string

【卡包跳转目标】枚举值：PAYMENT_CODE：跳转至微信支付付款码，点击“立即使用”跳转至微信支付付款码 MINI_PROGRAM：跳转至小程序，点击“立即使用”跳转至配置的商家小程序（需要指定小程序appid和path） DEFAULT_PAGE：跳转至默认页，点击“立即使用”跳转至默认页面如未传该参数，则默认跳转至默认页。

可选取值：

PAYMENT_CODE: 点击“立即使用”跳转至微信支付付款码

MINI_PROGRAM: 点击“立即使用”跳转至配置的商家小程序（需要指定小程序appid和path）

DEFAULT_PAGE: 点击“立即使用”跳转至默认页面

mini_program_appid 　选填 string(128)

【小程序appid】跳转的小程序appid，跳转至小程序时必填。跳转的小程序appid需至少和一个可核销商户有绑定关系。

mini_program_path 　选填 string(128)

【小程序path】跳转的小程序path，跳转至小程序时必填。

coupon_use_rule 　必填 object

【核销规则】

属性

coupon_available_time 　选填 object

【券生效时间】允许指定券的特殊生效时间规则。
该字段暂未开放

属性

fixed_normal_coupon 　选填 object

【固定面额满减券使用规则】stock_type为NORMAL时必填

属性

goods_tag 　选填 array[string(128)]

【订单优惠标记】订单优惠标记，按json格式。
商户下单时需要传入相同的标记(goods_tag)，用户同时符合其他规则才能享受优惠
校验规则：
1、最多允许录入50个
2、每个订单优惠标记支持字母/数字/下划线，不超过128个UTF8字符。

trade_type 　选填 array[string]

【指定支付模式】允许指定支付方式的交易才可核销/使用代金券，不填则默认“不限”。

可选取值：

MICROAPP: 小程序支付

APPPAY: APP支付

PPAY: 免密支付

CARD: 刷卡支付

FACE: 人脸支付

OTHER: 其他支付，公众号、扫码等

combine_use 　选填 boolean

【是否可叠加其他优惠】允许指定本优惠是否可以和本商户号创建的其他券同时使用，不填则默认为：“不允许同时使用”。枚举值：true：是false：否

available_items 　选填 array[string(128)]

【可核销商品编码】包含指定SKU商品编码的交易才可核销/使用代金券：活动商户在交易下单时，需传入用户购买的所有SKU商品编码，当命中代金券中设置的商品编码时可享受优惠。
校验规则：
1、单个商品编码的字符长度为【1，128】
2、条目个数限制为【1，50】

unavailable_items 　选填 array[string(128)]

【不参与优惠商品编码】该字段暂未开放
包含指定SKU商品编码的交易不可核销/使用代金券。
校验规则：
1、单个商品编码的字符长度为【1，128】
2、条目个数限制为【1，50】

available_merchants 　必填 array[string(20)]

【可核销商户号】可用商户的交易才可核销/使用代金券。当营销经费no_cash=false时，可用商户允许填入任何类型的特约商户或普通商户
当营销经费no_cash=true时，分为以下几种情况：
1、创建商户是普通商户或服务商特约商户(子商户)：可添加本商户号或同品牌商户。
说明：若可用商户中，有特约商户(子商户)，那么特约商户自己发起的交易、以及服务商帮特约商户发起的交易，都可以使用代金券。
2、创建商户是普通服务商：可添加已授权的子商户，详见《申请免充值代金券产品权限》。
说明：特约商户如果有多个服务商，那么服务商为他发起的交易，只要完成了免充值授权，都可以使用代金券；特约商户自己发起的交易不可以使用代金券。
3、创建商户是渠道商、银行服务商或从业机构：可直接添加旗下任意子商户，不需要子商户授权。
校验规则：条目个数限制为【1，50】

limit_card 　选填 object

【指定银行卡BIN】指定银行卡bin付款的交易可核销/使用代金券，当批次限定了指定银行卡时方可生效

属性

limit_pay 　选填 array[string(32)]

【指定付款方式】指定付款方式的交易可核销/使用代金券，可指定零钱付款、指定银行卡付款，需填入银行卡编码.xlsx，不在此列表中的银行卡，暂不支持此功能。黄色标记部分为不可使用的银行。
校验规则：条目个数限制为【1，1】。
零钱：CFT

no_cash 　必填 boolean

【营销经费】营销经费。
枚举值：
true：免充值
false：预充值
1、免充值：制券方无需提前充值资金，用户核销代金券时，直接从订单原价中扣除优惠减价金额，最终只将用户实际支付的金额结算给核销商户，商户实收少于订单原价。
2、预充值：制券方需将优惠预算提前充值到微信支付商户可用余额中，用户核销代金券时，系统从制券方商户可用余额中扣除优惠减价部分对应的资金，连同用户实际支付的资金，一并结算给核销商户，不影响实收。

stock_type 　必填 string(16)

【批次类型】批次类型，仅支持：
NORMAL：固定面额满减券批次

out_request_no 　必填 string(128)

【商户单据号】商户创建批次凭据号（格式：商户id+日期+流水号），可包含英文字母，数字，|，_，*，-等内容，不允许出现其他不合法符号，商户侧需保持商户单据号全局唯一。

ext_info 　选填 string(128)

【扩展属性】扩展属性字段，按json格式，如无需要则不填写。
该字段暂未开放

请求示例

POST

1curl -X POST \
2  https://api.mch.weixin.qq.com/v3/marketing/favor/coupon-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    "comment" : "零售批次",
9    "belong_merchant" : "98568865",
10    "available_begin_time" : "2015-05-20T13:29:35.120+08:00",
11    "available_end_time" : "2015-05-20T13:29:35.120+08:00",
12    "stock_use_rule" : {
13      "max_coupons" : 100,
14      "max_amount" : 5000,
15      "max_amount_by_day" : 400,
16      "max_coupons_per_user" : 3,
17      "natural_person_limit" : false,
18      "prevent_api_abuse" : false
19    },
20    "pattern_info" : {
21      "description" : "微信支付营销代金券",
22      "merchant_logo" : "CDN地址",
23      "merchant_name" : "微信支付",
24      "background_color" : "COLOR010",
25      "coupon_image" : "https://qpic.cn/xxx",
26      "jump_target" : "PAYMENT_CODE",
27      "mini_program_appid" : "wx23232232323",
28      "mini_program_path" : "/path/index/index"
29    },
30    "coupon_use_rule" : {
31      "coupon_available_time" : {
32        "fix_available_time" : {
33          "available_week_day" : [
34            1
35          ],
36          "begin_time" : 0,
37          "end_time" : 3600
38        },
39        "second_day_available" : false,
40        "available_time_after_receive" : 7
41      },
42      "fixed_normal_coupon" : {
43        "coupon_amount" : 100,
44        "transaction_minimum" : 100
45      },
46      "goods_tag" : [
47        "123321"
48      ],
49      "trade_type" : [
50        "MICROAPP"
51      ],
52      "combine_use" : false,
53      "available_items" : [
54        "123321"
55      ],
56      "unavailable_items" : [
57        "789987"
58      ],
59      "available_merchants" : [
60        "9856000"
61      ],
62      "limit_card" : {
63        "name" : "精粹白金",
64        "bin" : [
65          "62542688"
66        ]
67      },
68      "limit_pay" : [
69        "BCZ_DEBIT"
70      ]
71    },
72    "no_cash" : false,
73    "stock_type" : "NORMAL",
74    "out_request_no" : "example_out_request_no",
75    "ext_info" : "{'exinfo1':'1234','exinfo2':'3456'}"
76  }'
77

应答参数

200 OK

stock_id 　必填 string

【批次号】微信为每个代金券批次分配的唯一ID。

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.120+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后重试
400	INVALID_REQUEST	OpenID与AppID不匹配	请使用AppID下的OpenID
400	INVALID_REQUEST	活动已结束或未激活	请检查批次状态
400	INVALID_REQUEST	非法的商户号	请检查商户号是否正确
400	MCH_NOT_EXISTS	商户号不合法	请输入正确的商户号
400	PARAM_ERROR	回调URL不能为空	请填写回调URL
400	PARAM_ERROR	回调商户不能为空	请填写回调商户
400	PARAM_ERROR	券ID必填	请填写券ID
400	PARAM_ERROR	AppID必填	请输入AppID
400	PARAM_ERROR	OpenID必填	请输入OpenID
400	PARAM_ERROR	页大小超过阈值	请不要超过最大的页大小
400	PARAM_ERROR	输入时间格式错误	请输入正确的时间格式
400	PARAM_ERROR	批次号必填	请输入批次号
400	PARAM_ERROR	商户号必填	请输入商户号
400	PARAM_ERROR	非法的批次状态	请检查批次状态
403	NO_AUTH	你配置的信息需要开通特殊权限	请参考：QA方案
403	NOT_ENOUGH	批次预算不足	请补充预算
403	REQUEST_BLOCKED	调用商户无权限	请开通产品权限后再调用该接口
403	REQUEST_BLOCKED	商户无权发券	调用接口的商户号无权发券，请检查是否是自己的批次或是已授权的批次。
403	REQUEST_BLOCKED	批次不支持跨商户发券	该批次未做跨商户号的授权，请授权后再发放
403	REQUEST_BLOCKED	用户被限领拦截	用户领取已经达到上限，请调高上限或停止发放。
403	REQUEST_BLOCKED	活动未开始或已结束	该活动未开始或已结束
403	USER_ACCOUNT_ABNORMAL	用户非法	该用户账号异常，无法领券。商家可联系微信支付或让用户联系微信支付客服处理。
404	RESOURCE_NOT_EXISTS	批次不存在	请检查批次ID是否正确
429	FREQUENCY_LIMITED	请求过于频繁	稍后重试

文档是否有帮助

更多支持

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