创建代金券批次API

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


通过调用此接口可创建代金券批次,包括预充值&免充值类型。

接口说明

适用对象:直连商户 服务商 渠道商

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

请求方式:POST

接口规则:https://wechatpay-api.gitbook.io/wechatpay-api-v3

接口频率:单个商户号调用频率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天后开始的批次

示例值: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 设置此字段,允许指定单天最大发券预算,单位:分。
校验规则:不能大于总预算
示例值: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、创建商户是渠道商、银行服务商或从业机构:可直接添加旗下任意子商户,不需要子商户授权。
示例值:['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+日期+流水号),可包含英文字母,数字,|,_,*,-等内容,不允许出现其他不合法符号,商户侧需保持商户单据号全局唯一。
扩展属性 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": "CDN地址",
		"merchant_name": "微信支付",
		" background_color": "色号",
		" coupon_image ": "图片cdn地址"
	},
	"coupon_use_rule": {
		"coupon_available_time": {
			"fix_available_time": {
				" available_week_day ": [
					1
				],
				" begin_time ": 0,
				" end_time ": 3600
			},
			"second_day_available": false,
			"available_time_after_receive": 1440
		},
		" 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": ""
}
    
{
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 接口限频 请降低调用频率

版本说明

关闭
V1.5
2020年12月27日
1.增加各个字段的校验规则说明
V1.4
2020年9月2日
1.去除字段 unavailable_items(不参与优惠商品编码)、disscount_coupon(折扣券使用规则)和exchange_coupon(换购券使用规则)
V1.3
2020年6月8日
1.核销规则(coupon_use_rule)中,新增字段【指定银行卡BIN(limit_card)】
V1.2
2020年3月19日
1.核销规则(coupon_use_rule)中,新增字段【指定支付方式(limit_pay)】
V1.1
2020年2月12日
1. 发券规则单用户可领数调整为60

技术咨询

反馈有奖