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

创建商家券API

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


商户可以通过该接口创建商家券。微信支付生成商家券批次后并返回商家券批次号给到商户,商户可调用发券接口发放该批次商家券。

商家券满减券预算控制从“金额”调整为“个数”周知


为更好的方便开发者创建管理商家券的满减券,微信支付将对满减券发放预算库存控制进行优化调整,即 从“总预算(单位元)”调整为“最大发放个数(单位个)” 具体如下:


调整前

满减券(券类型为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


策略正式上线时间: 11/2 中午12点


1)策略上线后,仅支持满减券传入max_coupons(批次最大发放个数)与max_coupons_by_day(单天发放上限个数)

2)原金额类控制字段:max_amount(批次总预算)与max_amount_by_day(单天发放上限金额)将不再生效;

3)策略仅对11/2中午2点上线后的新创建批次生效,在此时间点前创建的存量满减券批次不受影响。


策略灰度时间:10/15 18:00:00 至 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 券核销相关规则
参数名 变量 类型[长度限制] 必填 描述
+券可核销时间 coupon_available_time object 日期区间内可以使用优惠。
参数名 变量 类型[长度限制] 必填 描述
开始时间 available_begin_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秒。
注意:开始时间设置有效期最长为1年。
示例值:2015-05-20T13:29:35+08:00
结束时间 available_end_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秒。
注意:结束时间设置有效期最长为1年。
示例值:2015-05-20T13:29:35+08:00
生效后N天内有效 available_day_after_receive int 日期区间内,券生效后x天内有效。例如生效当天内有效填1,生效后2天内有效填2,以此类推……注意,用户在有效期开始前领取商家券,则从有效期第1天开始计算天数,用户在有效期内领取商家券,则从领取当天开始计算天数,无论用户何时领取商家券,商家券在活动有效期结束后均不可用。可配合wait_days_after_receive一同填写,也可单独填写。单独填写时,有效期内领券后立即生效,生效后x天内有效。
示例值:3
+ 固定周期有效时间段 available_week object 可以设置多个星期下的多个可用时间段,比如每周二10点到18点,用户自定义字段。
参数名 变量 类型[长度限制] 必填 描述
可用星期数 week_day array[int] 条件选填 0代表周日,1代表周一,以此类推
当填写available_day_time时,week_day必填
示例值:1, 2
+ 当天可用时间段 available_day_time array 可以填写多个时间段,最多不超过2个。
参数名 变量 类型[长度限制] 必填 描述
当天可用开始时间 begin_time int 当天可用开始时间,单位:秒,1代表当天0点0分1秒。
示例值:3600
当天可用结束时间 end_time int 当天可用结束时间,单位:秒,86399代表当天23点59分59秒。
示例值:86399
+ 无规律的有效时间段 irregulary_avaliable_time array 无规律的有效时间,多个无规律时间段,用户自定义字段。
参数名 变量 类型[长度限制] 必填 描述
开始时间 begin_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
结束时间 end_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
领取后N天开始生效 wait_days_after_receive int 日期区间内,用户领券后需等待x天开始生效。例如领券后当天开始生效则无需填写,领券后第2天开始生效填1,以此类推……用户在有效期开始前领取商家券,则从有效期第1天开始计算天数,用户在有效期内领取商家券,则从领取当天开始计算天数。无论用户何时领取商家券,商家券在活动有效期结束后均不可用。需配合available_day_after_receive一同填写,不可单独填写。
示例值:7
+固定面额满减券使用规则 fixed_normal_coupon object 三选一 stock_type为NORMAL时必填。
参数名 变量 类型[长度限制] 必填 描述
优惠金额 discount_amount int 优惠金额,单位:分。
特殊规则:取值范围 1 ≤ value ≤ 10000000
示例值:5
消费门槛 transaction_minimum int 消费门槛,单位:分。
特殊规则:取值范围 1 ≤ value ≤ 10000000
示例值:100
+折扣券使用规则 discount_coupon object stock_type为DISCOUNT时必填。
参数名 变量 类型[长度限制] 必填 描述
折扣比例 discount_percent int 折扣百分比,例如:88为八八折。
示例值:88
消费门槛 transaction_minimum int 消费门槛,单位:分。
特殊规则:取值范围 1 ≤ value ≤ 10000000
示例值:100
+换购券使用规则 exchange_coupon object stock_type为EXCHANGE时必填。
参数名 变量 类型[长度限制] 必填 描述
单品换购价 exchange_price int 单品换购价,单位:分。
特殊规则:取值范围 0 ≤ value ≤ 10000000
示例值:100
消费门槛 transaction_minimum int 消费门槛,单位:分。
特殊规则:取值范围 0 ≤ value ≤ 10000000
示例值:100
核销方式 use_method string[1,128] 枚举值:
OFF_LINE:线下滴码核销,点击券“立即使用”跳转展示券二维码详情。
MINI_PROGRAMS:线上小程序核销,点击券“立即使用”跳转至配置的商家小程序(需要添加小程序appid和path)。
PAYMENT_CODE:微信支付付款码核销,点击券“立即使用”跳转至微信支付钱包付款码。
SELF_CONSUME:用户自助核销,点击券“立即使用”跳转至用户自助操作核销界面(当前暂不支持用户自助核销)。
示例值:OFF_LINE
小程序appid mini_programs_appid string[1,32] 条件选填 核销方式为线上小程序核销才有效。
示例值:wx23232232323
小程序path mini_programs_path string[1,128] 条件选填 核销方式为线上小程序核销才有效。
示例值:/path/index/index
+发放规则 stock_send_rule object body 券发放相关规则
参数名 变量 类型[长度限制] 必填 描述
批次最大发放个数 max_coupons int 批次最大可发放个数限制
特殊规则:取值范围 1 ≤ value ≤ 1000000000
示例值:100
用户最大可领个数 max_coupons_per_user int 用户可领个数,每个用户最多100张券 。
示例值:5
单天发放上限个数 max_coupons_by_day int 单天发放上限个数(stock_type为DISCOUNT或EXCHANGE时可传入此字段控制单天发放上限)。
特殊规则:取值范围 1 ≤ value ≤ 1000000000
示例值:100
是否开启自然人限制 natural_person_limit bool 不填默认否,枚举值:
true:是
false:否
注:一个身份证号限领次数,这里如果开启的话 ,那一个身份证号只可以领取一次 (以防被羊毛党薅羊毛)
示例值:false
可疑账号拦截 prevent_api_abuse bool 不填默认否,枚举值:
true:是
false:否
如:黑灰产账号
示例值:false
是否允许转赠 transferable bool 不填默认否,枚举值:
true:是
false:否
该字段暂未开放
示例值:false
是否允许分享链接 shareable bool 不填默认否,枚举值:
true:是
false:否
该字段暂未开放
示例值:false
商户请求单号 out_request_no string[1,128] body 商户创建批次凭据号(格式:商户id+日期+流水号),商户侧需保持唯一性。
示例值:100002322019090134234sfdf
+自定义入口 custom_entrance object body 卡详情页面,可选择多种入口引导用户。
参数名 变量 类型[长度限制] 必填 描述
+小程序入口 mini_programs_info object 需要小程序APPID、path、入口文案、引导文案。如果需要跳转小程序,APPID、path、入口文案为必填,引导文案非必填。
appid要与归属商户号有M-A or M-m-suba关系。
注:请查看绑定关系说明文档
参数名 变量 类型[长度限制] 必填 描述
商家小程序appid mini_programs_appid string[1,32] 商家小程序appid要与归属商户号有M-A or M-m-suba关系。
校验规则:传入的APPID得是与调用方商户号(即请求头里面的商户号)有绑定关系的APPID 或 传入的APPID得是归属商户号有绑定关系的APPID
示例值:wx234545656765876
商家小程序path mini_programs_path string[1,128] 商家小程序path
示例值:/path/index/index
入口文案 entrance_words string[1,5] 入口文案,字数上限为5个,一个中文汉字/英文字母/数字均占用一个字数。
示例值:欢迎选购
引导文案 guiding_words string[1,6] 小程序入口引导文案,用户自定义字段。字数上限为6个,一个中文汉字/英文字母/数字均占用一个字数。
示例值:获取更多优惠
商户公众号appid appid string[1,32] 可配置商户公众号,从券详情可跳转至公众号,用户自定义字段。
校验规则:传入的APPID得是与调用方商户号(即请求头里面的商户号)有绑定关系的APPID 或 传入的APPID得是归属商户号有绑定关系的APPID
示例值:wx324345hgfhfghfg
营销馆id hall_id string[1,64] 填写微信支付营销馆的馆id,用户自定义字段。 营销馆需在商户平台 创建。
示例值:233455656
可用门店id store_id string[1,64] 填写代金券可用门店id,用户自定义字段。
示例值:233554655
code展示模式 code_display_mode string[1,8] 枚举值:
NOT_SHOW:不展示code
BARCODE:一维码
QRCODE:二维码
示例值:BARCODE
+样式信息 display_pattern_info object body 创建批次时的样式信息。
参数名 变量 类型[长度限制] 必填 描述
使用须知 description string[1,1000] 用于说明详细的活动规则,会展示在代金券详情页。
示例值:xxx门店可用
商户logo merchant_logo_url string[1,128] 商户logo的URL地址,仅支持通过《图片上传API》接口获取的图片URL地址。
1、商户logo大小需为120像素*120像素。
2、支持JPG/JPEG/PNG格式,且图片小于1M。
示例值:https://qpic.cn/xxx
商户名称 merchant_name string[1,16] 商户名称,字数上限为16个,一个中文汉字/英文字母/数字均占用一个字数。
示例值:微信支付
背景颜色 background_color string[1,16] 券的背景颜色,可设置10种颜色,色值请参考卡券背景颜色图。颜色取值为颜色图中的颜色名称。
示例值:Color020
券详情图片 coupon_image_url string[1,128] 券详情图片,850像素*350像素,且图片大小不超过2M,支持JPG/PNG格式,仅支持通过《图片上传API》接口获取的图片URL地址。
示例值:https://qpic.cn/xxx
券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,调用发券接口时需指定券code;更多适用在微信支付平台流量场景(例如:支付有礼、支付有优惠等)
3、券code模式为MERCHANT_UPLOAD,需要调用上传预存code接口上传code,调用发券接口时无需指定code;更多用在商家自有流量场景(例如:商家自有小程序、H5网页等)

示例值:WECHATPAY_MODE
+事件通知配置 notify_config object body 事件回调通知商户的配置。
参数名 变量 类型[长度限制] 必填 描述
事件通知appid notify_appid string[1,64] 用于回调通知时,计算返回操作用户的openid(诸如领券用户),支持小程序or公众号的APPID;如该字段不填写,则回调通知中涉及到用户身份信息的openid与unionid都将为空。
示例值:wx23232232323
是否允许营销补贴 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"
  },
  "coupon_code_mode": "WECHATPAY_MODE"
}

    
{
JAVA示例代码
}
    

返回参数

参数名 变量 类型[长度限制] 必填 描述
批次号 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"
}
                                

    http://2323weixin.qq.com
                                

跳转小程序带参数说明

如果商家券配置了跳转小程序的入口(包括立即使用以及自定义入口),跳转链接会带有批次号、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已达上限 请更换一个新的批次后重试


文档调研

技术咨询

反馈有奖