基础支付
JSAPI支付
APP支付
H5支付
Native支付
小程序支付
合单支付
付款码支付
经营能力
微信支付分(免确认模式)
微信支付分(免确认预授权模式)
微信支付分(需确认模式)
微信支付分(公共API)
微信先享卡
支付即服务
行业方案
智慧商圈
营销工具
代金券
商家券
委托营销
消费卡
支付有礼
小程序发券插件
H5发券
图片上传(营销专用)
现金红包
资金应用
付款
分账
风险合规
消费者投诉2.0
其他能力
清关报关
图片上传
视频上传

创建代金券批次API

最新更新时间:2020.12.27 版本说明


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

接口说明

适用对象: 直连商户

请求URL:https://api.mch.weixin.qq.com/v3/marketing/favor/coupon-stocks

请求方式:POST

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

接口耗时:80ms


path 指该参数需在请求URL传参

query 指该参数需在请求URL传参

body 指该参数需在请求JSON传参


请求参数

参数名 变量 类型[长度限制] 必填 描述
批次名称 stock_name string[1,20] body 批次名称
校验规则:
1、批次名称最多9个中文汉字
2、批次名称最多20个字母
3、批次名称中不能包含不当内容和特殊字符 _ , ; |

示例值:微信支付代金券批次
批次备注 comment string[1,60] body 仅制券商户可见,用于自定义信息。
校验规则:批次备注最多60个UTF8字符数
示例值:零售批次
归属商户号 belong_merchant string[1,20] body 批次归属商户号
本字段暂未开放生效,但入参时请设置为当前创建代金券商户号即不会报错,暂时不支持入参其他的商户号
示例值:98568865
可用时间-开始时间 available_begin_time string[1,32] body 批次开始时间,遵循rfc3339标准格式,格式为YYYY-MM-DDTHH:mm:ss.sss+TIMEZONE,YYYY-MM-DD表示年月日,T出现在字符串中,表示time元素的开头,HH:mm:ss.sss表示时分秒毫秒,TIMEZONE表示时区(+08:00表示东八区时间,领先UTC 8小时,即北京时间)。例如:2015-05-20T13:29:35.120+08:00表示,北京时间2015年5月20日 13点29分35秒。
校验规则:
1、开始时间不可早于当前时间
2、不能创建365天后开始的批次
3、批次可用时间范围最长为90天

示例值:2015-05-20T13:29:35.120+08:00
可用时间-结束时间 available_end_time string[1,32] body 批次结束时间,遵循rfc3339标准格式,格式为YYYY-MM-DDTHH:mm:ss.sss+TIMEZONE,YYYY-MM-DD表示年月日,T出现在字符串中,表示time元素的开头,HH:mm:ss.sss表示时分秒毫秒,TIMEZONE表示时区(+08:00表示东八区时间,领先UTC 8小时,即北京时间)。例如:2015-05-20T13:29:35.120+08:00表示,北京时间2015年5月20日 13点29分35秒。
校验规则:
1、结束时间需晚于开始时间
2、可用时间最长为90天
3、有效时间间隔最短为1s

示例值:2015-05-20T13:29:35.120+08:00
+发放规则 stock_use_rule object body 批次使用规则
参数名 变量 类型[长度限制] 必填 描述
发放总上限 max_coupons uint64 最大发券数
校验规则:
1、发放总个数最少5个
2、发放总个数最多1000万个

示例值:100
总预算 max_amount uint64 最大发券预算,当营销经费no_cash选择预充值false时,激活批次时会从制券商户的余额中扣除预算,请保证账户金额充足,单位:分
max_amount需要等于coupon_amount(面额) * max_coupons(发放总上限)

校验规则:批次总预算最多1亿元
示例值:5000
单天预算发放上限 max_amount_by_day uint64 设置此字段,允许指定单天最大发券预算,单位:分。
校验规则:
1、不能大于总预算
2、max_amount_by_day不可以为0

示例值:400
单个用户可领个数 max_coupons_per_user uint32 活动期间每个用户可领个数,当开启了自然人限领时,多个微信号同属于一个身份证时,视为同一用户。
校验规则:
1、不能大于发放总个数
2、最少为1个,最多为60个

示例值:3
是否开启自然人限制 natural_person_limit bool 当开启了自然人限领时,多个微信号同属于一个身份证时,视为同一用户,枚举值
true:是
false:否
示例值:false
是否开启防刷拦截 prevent_api_abuse bool 若开启防刷拦截,当用户命中恶意、小号、机器、羊毛党、黑产等风险行为时,无法成功发放代金券。
枚举值
true:是
false:否
示例值:false
+样式设置 pattern_info object body 代金券详情页
参数名 变量 类型[长度限制] 必填 描述
使用说明 description string[1,3000] 用于说明详细的活动规则,会展示在代金券详情页。
校验规则:最多1000个UTF8字符
示例值:微信支付营销代金券
商户logo merchant_logo string[1,128] 商户logo ,仅支持通过《图片上传API》接口获取的图片URL地址。
1、商户logo大小需为120像素*120像素。
2、支持JPG/JPEG/PNG格式,且图片小于1M。
3、最多128个UTF8字符
示例值:https://qpic.cn/xxx
品牌名称 merchant_name string[1,128] 品牌名称,展示在用户卡包
校验规则:
1、最多12个中文汉字
2、最多36个英文字符

示例值:微信支付
背景颜色 background_color string[1,15] 券的背景颜色,可设置10种颜色,色值请参考卡券背景颜色图。颜色取值为颜色图中的颜色名称。可选枚举字段不用则不传,不可以传空值
示例值:COLOR020
券详情图片 coupon_image string[1,128] 券详情图片, 850像素*350像素,且图片大小不超过2M,支持JPG/PNG格式,仅支持通过《图片上传API》接口获取的图片URL地址。。
示例值:https://qpic.cn/xxx
+核销规则 coupon_use_rule object body 核销规则
参数名 变量 类型[长度限制] 必填 描述
+券生效时间 coupon_available_time object 允许指定券的特殊生效时间规则。
该字段暂未开放
参数名 变量 类型[长度限制] 必填 描述
+ 固定时间段可用 fix_available_time object 允许指定券在特殊时间段生效。当设置固定时间段可用时不可设置领取后N天有效
该字段暂未开放
参数名 变量 类型[长度限制] 必填 描述
可用星期数 available_week_day uint32 允许指定每周固定星期数生效,0代表周日生效,1代表周一生效,以此类推;不填则代表在可用时间内周一至周日都生效。
该字段暂未开放
示例值:1,2
当天开始时间 begin_time uint32 允许指定特殊生效星期数中的具体生效的时间段。
当天开始时间,单位:秒。
该字段暂未开放
示例值:0
当天结束时间 end_time uint32 允许指定特殊生效星期数中的具体生效的时间段。
当天结束时间,单位:秒,默认为23点59分59秒。
该字段暂未开放
示例值:3600
领取后N天有效 second_day_available bool 领取后,券的开始时间为领券后第二天,如7月1日领券,那么在7月2日00:00:00开始。
当设置领取后N天有效时,不可设置固定时间段可用。
枚举值:
true:是
false:否
该字段暂未开放
示例值:false
领取后有效时间 available_time_after_receive uint32 领取后,券的结束时间为领取N天后,如设置领取后7天有效,那么7月1日领券,在7月7日23:59:59失效(在可用时间内计算失效时间,若券还未到领取后N天,但是已经到了可用结束时间,那么也会过期)
领取后有效时间,单位:分钟。
该字段暂未开放
示例值:1440
+固定面额满减券使用规则 fixed_normal_coupon object stock_type为NORMAL时必填。
参数名 变量 类型[长度限制] 必填 描述
面额 coupon_amount uint64 面额,单位:分。
校验规则:
1、必须为整数
2、必须大于1分且小于等于1000元

示例值:100
门槛 transaction_minimum uint64 使用券金额门槛,单位:分。
若指定可核销商品编码,门槛则为可核销商品部分的消费金额,而不是订单的消费金额。
校验规则:使用门槛必须大于优惠金额
示例值:100
订单优惠标记 goods_tag array 订单优惠标记,按json格式。
商户下单时需要传入相同的标记(goods_tag),用户同时符合其他规则才能享受优惠
校验规则:
1、最多允许录入50个
2、每个订单优惠标记支持字母/数字/下划线,不超过128个UTF8字符。

示例值:["123321","456654"]
指定付款方式 limit_pay array[1,1] 指定付款方式的交易可核销/使用代金券,可指定零钱付款、指定银行卡付款,需填入支付方式编码, 不在此列表中的银行卡,暂不支持此功能。
校验规则:条目个数限制为【1,1】。
示例值:ICBC_CREDIT
+ 指定银行卡BIN limit_card object 指定银行卡bin付款的交易可核销/使用代金券,当批次限定了指定银行卡时方可生效
参数名 变量 类型[长度限制] 必填 描述
银行卡名称 name string[1,4] 将在微信支付收银台向用户展示,最多4个中文汉字
示例值:精粹白金
指定卡BIN bin array 使用指定卡BIN的银行卡支付方可享受优惠,按json格式
特殊规则:单个卡BIN的字符长度为【6,9】,条目个数限制为【1,10】。
示例值:['62123456','62123457']
支付方式 trade_type array 允许指定支付方式的交易才可核销/使用代金券,不填则默认“不限”。
枚举值:
MICROAPP:小程序支付
APPPAY:APP支付
PPAY:免密支付
CARD:刷卡支付
FACE:人脸支付
OTHER:其他支付
示例值:["MICROAPP","APPPAY"]
是否可叠加其他优惠 combine_use bool 允许指定本优惠是否可以和本商户号创建的其他券同时使用,不填则默认允许同时使用。枚举值:
true:是
false:否
示例值:false
可核销商品编码 available_items array 包含指定SKU商品编码的交易才可核销/使用代金券:活动商户在交易下单时,需传入用户购买的所有SKU商品编码,当命中代金券中设置的商品编码时可享受优惠。
校验规则:
1、单个商品编码的字符长度为【1,128】
2、条目个数限制为【1,50】

示例值:['123321','456654']
不可核销商品编码 unavailable_items array 该字段暂未开放
包含指定SKU商品编码的交易不可核销/使用代金券。
校验规则:
1、单个商品编码的字符长度为【1,128】
2、条目个数限制为【1,50】

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

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

批次类型 stock_type string[1,16]

body 批次类型,仅支持:
NORMAL:固定面额满减券批次
示例值:NORMAL

商户单据号 out_request_no string[1,128] body 商户创建批次凭据号(格式:商户id+日期+流水号),可包含英文字母,数字,|,_,*,-等内容,不允许出现其他不合法符号,商户侧需保持商户单据号全局唯一。
示例值:89560002019101000121
扩展属性 ext_info string[1,128] body 扩展属性字段,按json格式,如无需要则不填写。
该字段暂未开放
示例值:{'exinfo1':'1234','exinfo2':'3456'}

请求示例


{
	"stock_name": "微信支付代金券批次",
	"comment": "零售批次",
	"belong_merchant": "98568865",
	"available_begin_time": "2015-05-20T13:29:35.120+08:00",
	"available_end_time": "2015-05-20T13:29:35.120+08:00",
	" stock_use_rule": {
		"max_coupons": 100,
		"max_amount": 5000,
		"max_amount_by_day": 400,
		"max_coupons_per_user": 3,
		"natural_person_limit": false,
		"prevent_api_abuse": false
	},
	"pattern_info": {
		"description": "微信支付营销代金券",
		"merchant_logo": "https://qpic.cn/xxx",
		"merchant_name": "微信支付",
		"background_color": "COLOR020",
		"coupon_image": "https://qpic.cn/xxx"
	},
	"coupon_use_rule": {
		
		"fixed_normal_coupon": {
			"coupon_amount": 50,
			"transaction_minimum": 100
		},
		
		"goods_tag": [
			"123321",
			"123322"
		],
		"trade_type": ["OTHER","APPPAY"],
		"combine_use": false,
		"available_items": [
			"123321",
			"123322"
		],
		"available_merchants": [
			"9856000",
			"9856001"
		]
	},
	"no_cash": false,
	"stock_type": "NORMAL",
	"out_request_no": "89560002019101000121"
}
    
{
JAVA示例代码
}
    

返回参数

参数名 变量 类型[长度限制] 必填 描述
批次号 stock_id string[1,20] 微信为每个代金券批次分配的唯一ID。
示例值:98065001
创建时间 create_time string[1,32] 创建时间,遵循rfc3339标准格式,格式为YYYY-MM-DDTHH:mm:ss.sss+TIMEZONE,YYYY-MM-DD表示年月日,T出现在字符串中,表示time元素的开头,HH:mm:ss.sss表示时分秒毫秒,TIMEZONE表示时区(+08:00表示东八区时间,领先UTC 8小时,即北京时间)。例如:2015-05-20T13:29:35.120+08:00表示,北京时间2015年5月20日 13点29分35秒。
示例值:2015-05-20T13:29:35.120+08:00

返回示例


{
  "stock_id": "98065001",
  "create_time": "2015-05-20T13:29:35.120+08:00"

}
                                

    http://2323weixin.qq.com
                                

错误码公共错误码

状态码 错误码 描述 解决方案
400 PARAM_ERROR 回调url不能为空 请填写回调url
PARAM_ERROR 回调商户不能为空 请填写回调商户
PARAM_ERROR 券id必填 请填写券id
PARAM_ERROR appid必填 请输入appid
PARAM_ERROR openid必填 请输入openid
PARAM_ERROR 页大小超过阈值 请不要超过最大的页大小
PARAM_ERROR 输入时间格式错误 请输入正确的时间格式
PARAM_ERROR 批次号必填 请输入批次号
PARAM_ERROR 商户号必填 请输入商户号
PARAM_ERROR 非法的批次状态 请检查批次状态
400 MCH_NOT_EXISTS 商户号不合法 请输入正确的商户号
400 INVALID_REQUEST openid与appid不匹配 请使用appid下的openid
INVALID_REQUEST 活动已结束或未激活 请检查批次状态
INVALID_REQUEST 非法的商户号 请检查商户号是否正确
400 APPID_MCHID_NOT_MATCH 商户号与appid不匹配 请绑定调用接口的商户号和appid后重试
403 USER_ACCOUNT_ABNORMAL 用户非法 该用户账号异常,无法领券。商家可联系微信支付或让用户联系微信支付客服处理。
403 NOT_ENOUGH 批次预算不足 请补充预算
403 REQUEST_BLOCKED 调用商户无权限 请开通产品权限后再调用该接口
REQUEST_BLOCKED 商户无权发券 调用接口的商户号无权发券,请检查是否是自己的批次或是已授权的批次。
REQUEST_BLOCKED 批次不支持跨商户发券 该批次未做跨商户号的授权,请授权后再发放
REQUEST_BLOCKED 用户被限领拦截 用户领取已经达到上限,请调高上限或停止发放。
404 RESOURCE_NOT_EXISTS 批次不存在 请检查批次ID是否正确
429 FREQUENCY_LIMIT_EXCEED 接口限频 请降低调用频率


文档调研

技术咨询

反馈有奖