添加商品券批次组

更新时间:2025.11.20

服务商可以通过该接口为已有的「多次优惠」商品券添加更多批次组,每个批次组创建时会批量创建多个商品券批次。同一个商品券的多个批次组可以实现品牌方多样化的投放需求。

前置条件:已创建商品券且商品券的 usage_mode 为 PROGRESSIVE_BUNDLE

接口说明

支持商户:【普通服务商】

请求方式:【POST】/v3/marketing/partner/product-coupon/product-coupons/{product_coupon_id}/stock-bundles

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

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

接口限频:20/秒(商户号维度)

请求参数
折叠全部参数

Header  HTTP头参数

 Authorization  必填 string

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


 Accept  必填 string

请设置为application/json


 Content-Type  必填 string

请设置为application/json


path  路径参数

 product_coupon_id  必填   string

【商品券ID】 商品券的唯一标识,创建商品券时由微信支付生成


body  包体参数

 out_request_no  必填   string(40)

【创建请求单号】 品牌创建批次请求流水号,品牌侧需保持唯一性,可使用 数字、大小写字母、下划线_、短横线- 组成,长度在6-40个字符之间


 stock_bundle  必填   object

【批次组】 为商品券创建的批次组详情

属性

 remark  选填   string(20)

【备注】 仅配置品牌方可见,用于自定义信息,最多20个UTF-8字符


 coupon_code_mode  必填   string

【券Code分配模式】 决定发券时用户商品券Code如何产生,批次组内每一个批次都会设置为此值

可选取值

  • WECHATPAY:  微信支付随机生成,发券时由微信支付系统自动随机生成券码,品牌方无需干预,微信支付随机生成的券Code长度限制为40个字符以内

  • UPLOAD:  品牌方预上传Code,品牌方需先使用【预上传券Code API(单券)】或【预上传券Code API(多次优惠)】上传自定义Code,微信支付系统发券时从中随机选取,当预存Code不足时可能影响发券,品牌应及时补充


 stock_send_rule  必填   object

【批次组发放规则】 批次组内的批次会继承此规则

属性

 max_count  必填   integer

【批次组发放次数总上限】 批次组在生命周期内总发放次数,最多 100,000,000 次。批次组内的所有批次会继承此上限。


 max_count_per_day  选填   integer

【批次组每日发放次数上限】 批次组在每天内发放次数上限,每日刷新,最多 100,000,000 次。默认不限制每日发放上限。

:为保证用户领取/使用多次优惠的体验,批次组内的首个批次会继承此上限,但其余批次会保持为不限制。


 max_count_per_user  必填   integer

【每个用户领取批次组次数上限】 每个用户最多可领取本批次组的次数,最多 100 次。批次组内的所有批次会继承此上限。


 progressive_bundle_usage_rule  选填   object

【多次优惠批次组使用规则】 包含组合内部每一个批次的优惠规则,会根据内部的优惠规则列表依次创建批次放入批次组,当且仅当 usage_mode 为 PROGRESSIVE_BUNDLE 时必填。

多次优惠的批次组下各轮次,需要保证每一轮次 “优惠力度”大于等于前一轮次。但是首轮除外,即首轮的“优惠力度”可以小于/大于/等于其他任意轮次。
具体定义:

  • 当满减券时:各轮次中“减免金额”数值,每轮次需大于等于前一轮次,首轮除外

  • 当折扣券时:各轮次中“减免百分比”数值,每轮次需大于等于前一轮次,首轮除外

  • 当兑换券时:各轮次中“兑换价”数值,每轮次需小于等于前一轮次,首轮除外

举例:考虑一组折扣券5次优惠

  • 8折、7折、6折、5折、4折:允许

  • 8折、8折、8折、8折、8折:允许

  • 6折、7折、6折、5折、4折:允许

  • 6折、7折、7折、7折、7折:允许

  • 6折、7折、8折、7折、7折:不允许,因为第三轮的“优惠力度”小于第二轮

  • 8折、7折、6折、7折、4折:不允许,因为第四轮的“优惠力度”小于第三轮

属性

 coupon_available_period  必填   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秒。

批次有效期最长不超过365天


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

批次有效期最长不超过365天


 available_days  选填   integer

【券生效后N天内可用】 日期区间内,券生效后 N 天内有效,最多365天。例如:

  • 生效当天内有效填 1

  • 生效后2天内有效填 2

  • 依此类推……

用户在有效期开始前领取商品券,则从有效期第1天开始计算天数,用户在有效期内领取商品券,则从领取当天开始计算天数,无论用户何时领取商品券,商品券在活动有效期结束后均不可用。

可配合 wait_days_after_receive 一同填写,也可单独填写。

:不可与 irregular_available_period_list 同时配置


 wait_days_after_receive  选填   integer

【领券后需等待N天才生效】 日期区间内,用户领券后需等待 N 天才开始生效,最多30天。例如:

  • 领券后当天开始生效则无需填写

  • 领券后第二天开始生效则填写 1

用户在有效期开始前领取商品券,则从有效期第1天开始计算天数,用户在有效期内领取商品券,则从领取当天开始计算天数。无论用户何时领取商品券,商品券在活动有效期结束后均不可用。

需配合 available_days 一同填写,不可单独填写

:不可与 irregular_available_period_list 同时配置


 weekly_available_period  选填   object

【每周固定可用时间】 日期区间内,每周固定时间可以使用。可与 available_days 和 wait_days_after_receive 一同配置,一同配置时条件需同时满足券才可用(时间范围取交集)。

:不可与 irregular_available_period_list 同时配置

属性

 day_list  必填   array[string]

【每周可用星期数】 每周特定星期X可用,在日期区间内每周循环有效。例如 配置 ["MONDAY", "FRIDAY"] 表示每周一和周五可用。

可选取值

  • MONDAY:  周一可用

  • TUESDAY:  周二可用

  • WEDNESDAY:  周三可用

  • THURSDAY:  周四可用

  • FRIDAY:  周五可用

  • SATURDAY:  周六可用

  • SUNDAY:  周日可用


 day_period_list  选填   array[object]

【当天可用时间段】 生效当天特定时间段内有效,可以配置多个时间段。最多可以配置 3 个时间段。不配置则全天可用。

属性

 begin_time  必填   integer

【当天可用开始时间】 当天可用时间距离当天 00:00:00 的秒数,如 60 表示当天 00:01:00 开始可用。取值范围 [0,86399] 且必须小于 end_time


 end_time  必填   integer

【当天可用结束时间】 当天结束可用时间距离当天 00:00:00 的秒数,如 86399 表示当天 23:59:59 结束可用。取值范围 [0,86399] 且必须大于 begin_time


 irregular_available_period_list  选填   array[object]

【指定可用时间段】 可以配置多个无规律时间段,不同区间内请勿重叠,最多可配置2个区间。

:不可与 available_dayswait_days_after_receiveweekly_available_period 同时配置

属性

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


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


 normal_coupon_list  选填   array[object]

【满减券使用规则】 当且仅当 type 为 NORMAL 时必填,其他类型不应填写

属性

 threshold  必填   integer

【门槛金额】 使用门槛金额,单位为分,达到该门槛后可享受满减优惠。门槛可以为0,即无门槛。例如:

  • 满 100 元可用填 10000

  • 满 0.01 元可用填 1


 discount_amount  必填   integer

【固定减免金额】 固定减免金额,单位为分。


 discount_coupon_list  选填   array[object]

【折扣券使用规则】 当且仅当 type 为 DISCOUNT 时必填,其他类型不应填写`

属性

 threshold  必填   integer

【门槛金额】 使用门槛金额,单位为分,达到该门槛后可享受折扣优惠。门槛可以为0,即无门槛。例如:

  • 满 100 元可用填 10000

  • 满 0.01 元可用填 1


 percent_off  必填   integer

【固定减免百分比】 表示减免金额为总金额的百分比。例如:填入 30 表示减免 30%,即打 7 折


 exchange_coupon_list  选填   array[object]

【兑换券使用规则】 当且仅当 type 为 EXCHANGE 时必填,其他类型不应填写

属性

 threshold  必填   integer

【门槛金额】 使用门槛金额,单位为分,达到该门槛后可进行兑换。门槛可以为0,即无门槛兑换。例如:

  • 满 100 元可用填 10000

  • 满 0.01 元可用填 1


 exchange_price  必填   integer

【固定兑换价格】 单位为分


 usage_rule_display_info  必填   object

【券使用规则展示信息】 券使用规则展示信息,批次组内每一个批次都会设置为此值

属性

 coupon_usage_method_list  必填   array[string]

【券使用方式列表】 可以配置多种使用方式

可选取值

  • OFFLINE:  线下滴码核销,点击券“立即使用”跳转展示券二维码详情(投放计划暂不支持此核销方式)

  • MINI_PROGRAM:  线上小程序核销,点击券“立即使用”跳转至配置的商家小程序(需要添加小程序AppID和Path)

  • APP:  APP核销,在商家APP内核销

  • PAYMENT_CODE:  微信支付付款码核销,点击券“立即使用”将跳转至微信支付钱包付款码,服务商可扫码核销用户券后再扫付款码发起下单,适合线下支付场景


 mini_program_appid  选填   string

【小程序AppID】 品牌方或服务商小程序AppID,可在微信公众平台查看,该小程序与品牌或服务商存在绑定关系。

在 coupon_usage_method_list 中包含 MINI_PROGRAM 时必填,需和 mini_program_path 一同填写。


 mini_program_path  选填   string

【小程序跳转路径】 品牌方或服务商小程序内部跳转路径。

在 coupon_usage_method_list 中包含 MINI_PROGRAM 时必填,需和 mini_program_appid 一同填写。


 app_path  选填   string

【APP跳转路径】 品牌方或服务商APP跳转路径,在 coupon_usage_method_list 中包含 APP 时必填。


 usage_description  必填   string(1000)

【券使用说明】 用于说明详细的券规则,长度不超过1000个UTF-8字符


 coupon_available_store_info  选填   object

【券可用门店信息】 用于描述全部可用门店信息,可配置小程序跳转地址进行展示

属性

 description  必填   string(1000)

【券可用门店描述】 告知用户本券可在哪些门店使用,长度不超过1000个UTF-8字符


 mini_program_appid  选填   string

【小程序AppID】 品牌方或服务商小程序AppID,用于展示可用门店列表的详细信息,可在微信公众平台查看,该小程序与品牌或服务商存在绑定关系。需和 mini_program_path 一同填写。


 mini_program_path  选填   string

【小程序跳转路径】 品牌方或服务商小程序内部展示可用门店列表的详细信息的页面跳转路径,需和 mini_program_appid 一同填写。


 coupon_display_info  必填   object

【用户商品券展示信息】 用户商品券在卡包中的展示详情,包括引导用户的自定义入口,批次组内每一个批次都会设置为此值

属性

 code_display_mode  必填   string

【用户商品券Code展示模式】 决定用户商品券Code在卡包中的展示形态

可选取值

  • INVISIBLE:  不展示Code

  • BARCODE:  条形码

  • QRCODE:  二维码


 background_color  选填   string

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


 entrance_mini_program  选填   object

【小程序入口】 展示跳转小程序的入口

属性

 appid  必填   string

【小程序AppID】 品牌方小程序的AppID,可在微信公众平台查看,该小程序与品牌存在绑定关系


 path  必填   string

【小程序跳转路径】 品牌方小程序内部跳转路径


 entrance_wording  必填   string(5)

【入口文案】 小程序入口文案,长度不超过5个UTF-8字符


 guidance_wording  必填   string(6)

【引导文案】 小程序入口引导文案,长度不超过6个UTF-8字符


 entrance_official_account  选填   object

【公众号入口】 展示跳转公众号的入口

属性

 appid  必填   string

【公众号AppID】 微信公众号唯一标识,可在微信公众平台查看,该公众号应与品牌方存在绑定关系


 entrance_finder  选填   object

【视频号入口】 展示跳转视频号的入口

属性

 finder_id  必填   string

【视频号ID】 关联视频号将展示在优惠券详情的顶部右侧,该视频号应与品牌方存在绑定关系


 finder_video_id  必填   string

【视频号视频ID】 券详情视频内容,支持配置关联视频号下的具体视频内容


 finder_video_cover_image_url  必填   string

【视频号封面图】 截取的视频号图片将在券到期提醒消息、券详情中展示,仅支持通过【图片上传API】获取的图片URL地址。

  • 图片尺寸:716像素(宽)*402像素(高)

  • 图片大小不超过2M

  • 建议图片格式:JPG/PNG格式


 notify_config  必填   object

【事件通知配置】 发生券相关事件时,微信支付会向品牌方发送通知,需要提供通知相关配置,批次组内每一个批次都会设置为此值

属性

 notify_appid  必填   string

【事件通知AppID】 服务商或者品牌的AppID,支持小程序、服务号、公众号、APP类型的AppID,可在微信公众平台查看,用于券事件通知时计算用户的OpenID,需要与服务商或者品牌存在绑定关系


 store_scope  必填   string

【可用门店范围】 控制该批次可以在品牌下哪些门店使用,批次组内每一个批次都会设置为此值

可选取值

  • NONE:  无关联门店,该批次对外不展示可用门店信息

  • ALL:  所有门店可用,该批次在品牌下的所有门店可用,品牌无需为该批次关联门店列表

  • SPECIFIC:  特定门店可用,品牌需调用关联门店接口关联门店,关联后该批次在关联的门店可用


 brand_id  必填   string

【品牌ID】 微信支付为品牌方分配的唯一标识,该品牌应与服务商存在授权关系

请求示例

curl
Java
Go

POST

1curl -X POST \
2  https://api.mch.weixin.qq.com/v3/marketing/partner/product-coupon/product-coupons/200000001/stock-bundles \
3  -H "Authorization: WECHATPAY2-SHA256-RSA2048 mchid=\"1900000001\",..." \
4  -H "Accept: application/json" \
5  -H "Content-Type: application/json" \
6  -d '{
7    "out_request_no" : "34657_20250101_123456",
8    "stock_bundle" : {
9      "remark" : "满减券",
10      "coupon_code_mode" : "UPLOAD",
11      "stock_send_rule" : {
12        "max_count" : 10000000,
13        "max_count_per_day" : 10000,
14        "max_count_per_user" : 1
15      },
16      "progressive_bundle_usage_rule" : {
17        "coupon_available_period" : {
18          "available_begin_time" : "2025-01-01T00:00:00+08:00",
19          "available_end_time" : "2025-10-01T00:00:00+08:00",
20          "available_days" : 10,
21          "wait_days_after_receive" : 1,
22          "weekly_available_period" : {
23            "day_list" : [
24              "MONDAY"
25            ],
26            "day_period_list" : [
27              {
28                "begin_time" : 60,
29                "end_time" : 86399
30              }
31            ]
32          },
33          "irregular_available_period_list" : [
34            {
35              "begin_time" : "2025-01-01T00:00:00+08:00",
36              "end_time" : "2025-10-01T00:00:00+08:00"
37            }
38          ]
39        },
40        "normal_coupon_list" : [
41          {
42            "threshold" : 10000,
43            "discount_amount" : 100
44          }
45        ],
46        "discount_coupon_list" : [
47          {
48            "threshold" : 10000,
49            "percent_off" : 30
50          }
51        ],
52        "exchange_coupon_list" : [
53          {
54            "threshold" : 10000,
55            "exchange_price" : 100
56          }
57        ]
58      },
59      "usage_rule_display_info" : {
60        "coupon_usage_method_list" : [
61          "MINI_PROGRAM"
62        ],
63        "mini_program_appid" : "wx1234567890",
64        "mini_program_path" : "/pages/index/product",
65        "app_path" : "https://www.example.com/jump-to-app",
66        "usage_description" : "全场可用",
67        "coupon_available_store_info" : {
68          "description" : "可在上海市区的所有门店使用,详细列表参考小程序内信息为准",
69          "mini_program_appid" : "wx1234567890",
70          "mini_program_path" : "/pages/index/store-list"
71        }
72      },
73      "coupon_display_info" : {
74        "code_display_mode" : "QRCODE",
75        "background_color" : "Color010",
76        "entrance_mini_program" : {
77          "appid" : "wx1234567890",
78          "path" : "/pages/index/product",
79          "entrance_wording" : "欢迎选购",
80          "guidance_wording" : "获取更多优惠"
81        },
82        "entrance_official_account" : {
83          "appid" : "wx1234567890"
84        },
85        "entrance_finder" : {
86          "finder_id" : "gh_12345678",
87          "finder_video_id" : "UDFsdf24df34dD456Hdf34",
88          "finder_video_cover_image_url" : "https://wxpaylogo.qpic.cn/wxpaylogo/xxxxx/xxx"
89        }
90      },
91      "notify_config" : {
92        "notify_appid" : "wx4fd12345678"
93      },
94      "store_scope" : "SPECIFIC"
95    },
96    "brand_id" : "120344"
97  }'
98

应答参数
折叠全部参数

200 OK

 stock_bundle_id  必填   string(40)

【批次组ID】 商品券批次组的唯一标识,由微信支付生成


 stock_list  必填   array[object]

【批次列表】 批次组内批次列表

属性

 product_coupon_id  必填   string(40)

【商品券ID】 商品券的唯一标识,由微信支付生成


 stock_id  必填   string(40)

【批次ID】 商品券批次的唯一标识,由微信支付生成


 remark  选填   string(20)

【备注】 仅配置品牌可见,用于自定义信息


 coupon_code_mode  必填   string

【券Code分配模式】 决定发券时用户商品券Code如何产生

可选取值

  • WECHATPAY:  微信支付随机生成,发券时由微信支付系统自动随机生成券码,品牌方无需干预,微信支付随机生成的券Code长度限制为40个字符以内

  • UPLOAD:  品牌方预上传Code,品牌方需先使用【预上传券Code API(单券)】或【预上传券Code API(多次优惠)】上传自定义Code,微信支付系统发券时从中随机选取,当预存Code不足时可能影响发券,品牌应及时补充


 coupon_code_count_info  选填   object

【品牌方预上传的券Code数量信息】 当且仅当 coupon_code_mode 为 UPLOAD 时存在此字段

属性

 total_count  必填   integer

【已上传的Code总数】 品牌方为此批次已经上传过的券Code总数量


 available_count  必填   integer

【当前可用的Code数】 品牌方为此批次已经上传过的券Code中,当前剩余可用的券Code数量


 stock_send_rule  必填   object

【发放规则】 发放规则

属性

 max_count  必填   integer

【发放次数总上限】 批次在生命周期内总发放次数,最多 100,000,000 次


 max_count_per_day  选填   integer

【每日发放次数上限】 批次在每天内发放次数上限,每日刷新,最多 100,000,000 次。默认不限制每日发放上限


 max_count_per_user  必填   integer

【每个用户领取次数上限】 每个用户最多可领取本批次的次数,最多 100 次。


 progressive_bundle_usage_rule  选填   object

【多次优惠使用规则】 本批次属于某个多次优惠批次组,这里记录的是本批次的使用规则,当且仅当 usage_mode 为 PROGRESSIVE_BUNDLE 时提供,其他场景不提供

属性

 coupon_available_period  必填   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秒。

批次有效期最长不超过365天


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

批次有效期最长不超过365天


 available_days  选填   integer

【券生效后N天内可用】 日期区间内,券生效后 N 天内有效,最多365天。例如:

  • 生效当天内有效填 1

  • 生效后2天内有效填 2

  • 依此类推……

用户在有效期开始前领取商品券,则从有效期第1天开始计算天数,用户在有效期内领取商品券,则从领取当天开始计算天数,无论用户何时领取商品券,商品券在活动有效期结束后均不可用。

可配合 wait_days_after_receive 一同填写,也可单独填写。

:不可与 irregular_available_period_list 同时配置


 wait_days_after_receive  选填   integer

【领券后需等待N天才生效】 日期区间内,用户领券后需等待 N 天才开始生效,最多30天。例如:

  • 领券后当天开始生效则无需填写

  • 领券后第二天开始生效则填写 1

用户在有效期开始前领取商品券,则从有效期第1天开始计算天数,用户在有效期内领取商品券,则从领取当天开始计算天数。无论用户何时领取商品券,商品券在活动有效期结束后均不可用。

需配合 available_days 一同填写,不可单独填写

:不可与 irregular_available_period_list 同时配置


 weekly_available_period  选填   object

【每周固定可用时间】 日期区间内,每周固定时间可以使用。可与 available_days 和 wait_days_after_receive 一同配置,一同配置时条件需同时满足券才可用(时间范围取交集)。

:不可与 irregular_available_period_list 同时配置

属性

 day_list  必填   array[string]

【每周可用星期数】 每周特定星期X可用,在日期区间内每周循环有效。例如 配置 ["MONDAY", "FRIDAY"] 表示每周一和周五可用。

可选取值

  • MONDAY:  周一可用

  • TUESDAY:  周二可用

  • WEDNESDAY:  周三可用

  • THURSDAY:  周四可用

  • FRIDAY:  周五可用

  • SATURDAY:  周六可用

  • SUNDAY:  周日可用


 day_period_list  选填   array[object]

【当天可用时间段】 生效当天特定时间段内有效,可以配置多个时间段。最多可以配置 3 个时间段。不配置则全天可用。

属性

 begin_time  必填   integer

【当天可用开始时间】 当天可用时间距离当天 00:00:00 的秒数,如 60 表示当天 00:01:00 开始可用。取值范围 [0,86399] 且必须小于 end_time


 end_time  必填   integer

【当天可用结束时间】 当天结束可用时间距离当天 00:00:00 的秒数,如 86399 表示当天 23:59:59 结束可用。取值范围 [0,86399] 且必须大于 begin_time


 irregular_available_period_list  选填   array[object]

【指定可用时间段】 可以配置多个无规律时间段,不同区间内请勿重叠,最多可配置2个区间。

:不可与 available_dayswait_days_after_receiveweekly_available_period 同时配置

属性

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


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


 normal_coupon  选填   object

【满减券使用规则】 当且仅当 type 为 NORMAL 时必填,其他类型不应填写

属性

 threshold  必填   integer

【门槛金额】 使用门槛金额,单位为分,达到该门槛后可享受满减优惠。门槛可以为0,即无门槛。例如:

  • 满 100 元可用填 10000

  • 满 0.01 元可用填 1


 discount_amount  必填   integer

【固定减免金额】 固定减免金额,单位为分。


 discount_coupon  选填   object

【折扣券使用规则】 当且仅当 type 为 DISCOUNT 时必填,其他类型不应填写`

属性

 threshold  必填   integer

【门槛金额】 使用门槛金额,单位为分,达到该门槛后可享受折扣优惠。门槛可以为0,即无门槛。例如:

  • 满 100 元可用填 10000

  • 满 0.01 元可用填 1


 percent_off  必填   integer

【固定减免百分比】 表示减免金额为总金额的百分比。例如:填入 30 表示减免 30%,即打 7 折


 exchange_coupon  选填   object

【兑换券使用规则】 当且仅当 type 为 EXCHANGE 时必填,其他类型不应填写

属性

 threshold  必填   integer

【门槛金额】 使用门槛金额,单位为分,达到该门槛后可进行兑换。门槛可以为0,即无门槛兑换。例如:

  • 满 100 元可用填 10000

  • 满 0.01 元可用填 1


 exchange_price  必填   integer

【固定兑换价格】 单位为分


 stock_bundle_info  必填   object

【批次组信息】 批次所在批次组信息

属性

 stock_bundle_id  必填   string(40)

【批次所属批次组ID】 商品券批次组的唯一标识,【创建商品券(多次优惠)】或【添加商品券批次组】时由微信支付生成


 stock_bundle_index  必填   integer

【批次在批次组内的次序】 本批次在批次组内的次序,从0开始


 usage_rule_display_info  必填   object

【券使用规则展示信息】 券使用规则展示信息

属性

 coupon_usage_method_list  必填   array[string]

【券使用方式列表】 可以配置多种使用方式

可选取值

  • OFFLINE:  线下滴码核销,点击券“立即使用”跳转展示券二维码详情(投放计划暂不支持此核销方式)

  • MINI_PROGRAM:  线上小程序核销,点击券“立即使用”跳转至配置的商家小程序(需要添加小程序AppID和Path)

  • APP:  APP核销,在商家APP内核销

  • PAYMENT_CODE:  微信支付付款码核销,点击券“立即使用”将跳转至微信支付钱包付款码,服务商可扫码核销用户券后再扫付款码发起下单,适合线下支付场景


 mini_program_appid  选填   string

【小程序AppID】 品牌方或服务商小程序AppID,可在微信公众平台查看,该小程序与品牌或服务商存在绑定关系。

在 coupon_usage_method_list 中包含 MINI_PROGRAM 时必填,需和 mini_program_path 一同填写。


 mini_program_path  选填   string

【小程序跳转路径】 品牌方或服务商小程序内部跳转路径。

在 coupon_usage_method_list 中包含 MINI_PROGRAM 时必填,需和 mini_program_appid 一同填写。


 app_path  选填   string

【APP跳转路径】 品牌方或服务商APP跳转路径,在 coupon_usage_method_list 中包含 APP 时必填。


 usage_description  必填   string(1000)

【券使用说明】 用于说明详细的券规则,长度不超过1000个UTF-8字符


 coupon_available_store_info  选填   object

【券可用门店信息】 用于描述全部可用门店信息,可配置小程序跳转地址进行展示

属性

 description  必填   string(1000)

【券可用门店描述】 告知用户本券可在哪些门店使用,长度不超过1000个UTF-8字符


 mini_program_appid  选填   string

【小程序AppID】 品牌方或服务商小程序AppID,用于展示可用门店列表的详细信息,可在微信公众平台查看,该小程序与品牌或服务商存在绑定关系。需和 mini_program_path 一同填写。


 mini_program_path  选填   string

【小程序跳转路径】 品牌方或服务商小程序内部展示可用门店列表的详细信息的页面跳转路径,需和 mini_program_appid 一同填写。


 coupon_display_info  必填   object

【用户商品券展示信息】 用户商品券在卡包中的展示详情,包括引导用户的自定义入口

属性

 code_display_mode  必填   string

【用户商品券Code展示模式】 决定用户商品券Code在卡包中的展示形态

可选取值

  • INVISIBLE:  不展示Code

  • BARCODE:  条形码

  • QRCODE:  二维码


 background_color  选填   string

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


 entrance_mini_program  选填   object

【小程序入口】 展示跳转小程序的入口

属性

 appid  必填   string

【小程序AppID】 品牌方小程序的AppID,可在微信公众平台查看,该小程序与品牌存在绑定关系


 path  必填   string

【小程序跳转路径】 品牌方小程序内部跳转路径


 entrance_wording  必填   string(5)

【入口文案】 小程序入口文案,长度不超过5个UTF-8字符


 guidance_wording  必填   string(6)

【引导文案】 小程序入口引导文案,长度不超过6个UTF-8字符


 entrance_official_account  选填   object

【公众号入口】 展示跳转公众号的入口

属性

 appid  必填   string

【公众号AppID】 微信公众号唯一标识,可在微信公众平台查看,该公众号应与品牌方存在绑定关系


 entrance_finder  选填   object

【视频号入口】 展示跳转视频号的入口

属性

 finder_id  必填   string

【视频号ID】 关联视频号将展示在优惠券详情的顶部右侧,该视频号应与品牌方存在绑定关系


 finder_video_id  必填   string

【视频号视频ID】 券详情视频内容,支持配置关联视频号下的具体视频内容


 finder_video_cover_image_url  必填   string

【视频号封面图】 截取的视频号图片将在券到期提醒消息、券详情中展示,仅支持通过【图片上传API】获取的图片URL地址。

  • 图片尺寸:716像素(宽)*402像素(高)

  • 图片大小不超过2M

  • 建议图片格式:JPG/PNG格式


 notify_config  必填   object

【事件通知配置】 发生券相关事件时,微信支付会向服务商发送通知,需要提供通知相关配置

属性

 notify_appid  必填   string

【事件通知AppID】 服务商或者品牌的AppID,支持小程序、服务号、公众号、APP类型的AppID,可在微信公众平台查看,用于券事件通知时计算用户的OpenID,需要与服务商或者品牌存在绑定关系


 store_scope  必填   string

【可用门店范围】 控制该批次可以在品牌下哪些门店使用

可选取值

  • NONE:  无关联门店,该批次对外不展示可用门店信息

  • ALL:  所有门店可用,该批次在品牌下的所有门店可用,品牌无需为该批次关联门店列表

  • SPECIFIC:  特定门店可用,品牌需调用关联门店接口关联门店,关联后该批次在关联的门店可用


 sent_count_info  必填   object

【已发放次数】 本批次已发放次数

属性

 total_count  必填   integer

【已发放总次数】 批次在生命周期内已发放次数


 today_count  必填   integer

【当天已发放次数】 批次在当天已发放次数


 state  必填   string

【批次状态】 商品券批次状态

可选取值

  • AUDITING:  审批中

  • SENDING:  发放中

  • PAUSED:  已暂停

  • STOPPED:  已停止,当前已到达结束时间

  • DEACTIVATED:  已失效,品牌方主动调用失效接口使批次失效


 deactivate_request_no  选填   string(128)

【失效请求单号】 当且仅当 state 为 DEACTIVATED 时提供,返回品牌方调用【失效商品券批次API】时传入的请求流水号


 deactivate_time  选填   string

【失效时间】 当且仅当 state 为 DEACTIVATED 时提供,遵循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秒。


 deactivate_reason  选填   string(150)

【失效原因】 当且仅当 state 为 DEACTIVATED 时提供,返回品牌方调用【失效商品券批次API】时传入的失效原因


 brand_id  必填   string

【品牌ID】 微信支付为品牌方分配的唯一标识,该品牌应与服务商存在授权关系

应答示例

200 OK

1{
2  "stock_bundle_id" : "123456789",
3  "stock_list" : [
4    {
5      "product_coupon_id" : "200000001",
6      "stock_id" : "123456789",
7      "remark" : "满减券",
8      "coupon_code_mode" : "UPLOAD",
9      "coupon_code_count_info" : {
10        "total_count" : 10000,
11        "available_count" : 999
12      },
13      "stock_send_rule" : {
14        "max_count" : 10000000,
15        "max_count_per_day" : 10000,
16        "max_count_per_user" : 1
17      },
18      "progressive_bundle_usage_rule" : {
19        "coupon_available_period" : {
20          "available_begin_time" : "2025-01-01T00:00:00+08:00",
21          "available_end_time" : "2025-10-01T00:00:00+08:00",
22          "available_days" : 10,
23          "wait_days_after_receive" : 1,
24          "weekly_available_period" : {
25            "day_list" : [
26              "MONDAY"
27            ],
28            "day_period_list" : [
29              {
30                "begin_time" : 60,
31                "end_time" : 86399
32              }
33            ]
34          },
35          "irregular_available_period_list" : [
36            {
37              "begin_time" : "2025-01-01T00:00:00+08:00",
38              "end_time" : "2025-10-01T00:00:00+08:00"
39            }
40          ]
41        },
42        "normal_coupon" : {
43          "threshold" : 10000,
44          "discount_amount" : 100
45        },
46        "discount_coupon" : {
47          "threshold" : 10000,
48          "percent_off" : 30
49        },
50        "exchange_coupon" : {
51          "threshold" : 10000,
52          "exchange_price" : 100
53        }
54      },
55      "stock_bundle_info" : {
56        "stock_bundle_id" : "123456789",
57        "stock_bundle_index" : 0
58      },
59      "usage_rule_display_info" : {
60        "coupon_usage_method_list" : [
61          "MINI_PROGRAM"
62        ],
63        "mini_program_appid" : "wx1234567890",
64        "mini_program_path" : "/pages/index/product",
65        "app_path" : "https://www.example.com/jump-to-app",
66        "usage_description" : "全场可用",
67        "coupon_available_store_info" : {
68          "description" : "可在上海市区的所有门店使用,详细列表参考小程序内信息为准",
69          "mini_program_appid" : "wx1234567890",
70          "mini_program_path" : "/pages/index/store-list"
71        }
72      },
73      "coupon_display_info" : {
74        "code_display_mode" : "QRCODE",
75        "background_color" : "Color010",
76        "entrance_mini_program" : {
77          "appid" : "wx1234567890",
78          "path" : "/pages/index/product",
79          "entrance_wording" : "欢迎选购",
80          "guidance_wording" : "获取更多优惠"
81        },
82        "entrance_official_account" : {
83          "appid" : "wx1234567890"
84        },
85        "entrance_finder" : {
86          "finder_id" : "gh_12345678",
87          "finder_video_id" : "UDFsdf24df34dD456Hdf34",
88          "finder_video_cover_image_url" : "https://wxpaylogo.qpic.cn/wxpaylogo/xxxxx/xxx"
89        }
90      },
91      "notify_config" : {
92        "notify_appid" : "wx4fd12345678"
93      },
94      "store_scope" : "SPECIFIC",
95      "sent_count_info" : {
96        "total_count" : 100,
97        "today_count" : 10
98      },
99      "state" : "SENDING",
100      "deactivate_request_no" : "1002600620019090123143254436",
101      "deactivate_time" : "2025-01-01T00:00+08:00",
102      "deactivate_reason" : "批次信息有误,重新创建",
103      "brand_id" : "120344"
104    }
105  ]
106}
107

 

错误码

以下是本接口返回的错误码列表。详细错误码规则,请参考微信支付接口规则-错误码和错误提示

状态码

错误码

描述

解决方案

400

PARAM_ERROR

参数错误

请根据错误提示正确传入参数

400

INVALID_REQUEST

HTTP 请求不符合微信支付 APIv3 接口规则

请参阅 接口规则

401

SIGN_ERROR

验证不通过

请参阅 签名常见问题

500

SYSTEM_ERROR

系统异常,请稍后重试

请稍后重试

400

INVALID_REQUEST

传入参数不符合业务规则

请参考文档中对每个字段的要求以及组合要求,确认请求参数是否满足

400

ALREADY_EXISTS

商品券批次组已存在

确认 out_request_no 字段是否重复使用,确保不同请求的 out_request_no 唯一

404

NOT_FOUND

未找到 product_coupon_id 对应的商品券

请确认 product_coupon_id 存在且属于当前品牌

429

RATELIMIT_EXCEEDED

请求超过接口频率限制

请稍后使用原参数重试

 

元宝AI
反馈
目录
置顶