查询商品券批次列表

更新时间：2025.08.28

品牌方可以通过该接口分页查询某个商品券的批次列表。

前置条件：已创建商品券

接口说明

支持商户：【品牌商户】

请求方式：【GET】/brand/marketing/product-coupon/product-coupons/{product_coupon_id}/stocks

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

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

请求参数

Header HTTP头参数

Authorization 　必填　string

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

Accept 　必填　string

请设置为application/json

Wechatpay-Serial 　必填　string

【微信支付公钥ID】请传入brand_id对应的微信支付公钥ID，接口将会校验两者的关联关系，参考微信支付公钥产品简介及使用说明获取微信支付公钥ID和相关的介绍。以下两种场景将使用到微信支付公钥： 1、接收到接口的返回内容，需要使用微信支付公钥进行验签； 2、调用含有敏感信息参数（如姓名、身份证号码）的接口时，需要使用微信支付公钥加密敏感信息后再传输参数，加密指引请参考微信支付公钥加密敏感信息指引。

path 路径参数

product_coupon_id 　必填 string

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

query 查询参数

state 　选填 string

【批次状态】不填默认查询所有状态的批次

可选取值

AUDITING: 审批中
SENDING: 发放中
PAUSED: 已暂停
STOPPED: 已停止，当前已到达结束时间
DEACTIVATED: 已失效，品牌方主动调用失效接口使批次失效

page_size 　选填 integer

【分页大小】单次拉取的数据条数上限，不填默认为20，最大值50

page_token 　选填 string

【分页Token】分页查询时，需要传入上一次调用返回的 next_page_token，首次调用不填

请求示例

GET

1curl -X GET \
2  https://api.mch.weixin.qq.com/brand/marketing/product-coupon/product-coupons/200000001/stocks?state=SENDING&page_size=20&page_token=MTIzMjUK \
3  -H "Authorization: WECHATPAY-BRAND-SHA256-RSA2048 brand_id=\"XXXX\",..." \
4  -H "Accept: application/json" \
5  -H "Wechatpay-Serial: PUB_KEY_ID_XXXX"  
6

应答参数

200 OK

total_count 　必填 integer

【总个数】符合查询条件的批次总数，当且仅当 page_token 为空时提供

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，微信支付系统发券时从中随机选取，当预存Code不足时可能影响发券，品牌应及时补充
API_ASSIGN: 品牌方自行指定，品牌方通过发券API自行发券时指定，微信支付系统不再进行自动分配。特别注意：这种模式的商品批次只可由品牌方自行发券，无法在摇一摇有优惠等微信支付渠道投放

coupon_code_count_info 　选填 object

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

属性

stock_send_rule 　必填 object

【发放规则】发放规则

属性

single_usage_rule 　选填 object

【单券使用规则】当且仅当 usage_mode 为 SINGLE 时提供，其他场景不提供

属性

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

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

available_days 　选填 integer

【生效后N天内有效】日期区间内，券生效后 N 天内有效，最多365天。例如：

生效当天内有效填 1
生效后2天内有效填 2
依此类推……

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

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

wait_days_after_receive 　选填 integer

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

领券后当天开始生效则无需填写
领券后第二天开始生效则填写 1

用户在有效期开始前领取商品券，则从有效期第1天开始计算天数，用户在有效期内领取商品券，则从领取当天开始计算天数。无论用户何时领取商品券，商品券在活动有效期结束后均不可用。需配合 available_days 一同填写，不可单独填写。

weekly_available_period 　选填 object

【每周固定可用时间】每周固定可用时间

属性

day_list 　选填 array[string]

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

可选取值

MONDAY: 周一可用
TUESDAY: 周二可用
WEDNESDAY: 周三可用
THURSDAY: 周四可用
FRIDAY: 周五可用
SATURDAY: 周六可用
SUNDAY: 周日可用

day_period_list 　选填 array[object]

【当天可用时间段】生效当天特定时间段内有效，可以配置多个时间段。最多可以配置 2 个时间段。不配置则全天可用。配置此字段后 day_list 字段必填

属性

begin_time 　必填 integer

【当天可用开始时间】当天可用时间距离当天 00:00::00 的秒数，如 60 表示当天 00:01:00 开始可用

end_time 　必填 integer

【当天可用结束时间】当天结束可用时间距离当天 00:00:00 的秒数，如 86399 表示当天 23:59:59 结束可用

irregular_available_period_list 　选填 array[object]

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

属性

normal_coupon 　选填 object

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

属性

threshold 　必填 integer

【门槛金额】使用门槛金额，单位为分，达到该门槛后可享受满减优惠。门槛不得为 0。例如：

满 100 元可用填 10000
满 0.01 元可用填 1

discount_amount 　必填 integer

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

discount_coupon 　选填 object

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

属性

threshold 　必填 integer

【门槛金额】使用门槛金额，单位为分，达到该门槛后可享受折扣优惠。门槛不得为 0。例如：

满 100 元可用填 10000
满 0.01 元可用填 1

percent_off 　必填 integer

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

exchange_coupon 　选填 object

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

属性

threshold 　必填 integer

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

满 100 元可用填 10000
满 0.01 元可用填 1

exchange_price 　必填 integer

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

sequential_usage_rule 　选填 object

【多次优惠使用规则】当且仅当 usage_mode 为 SEQUENTIAL 时提供，其他场景不提供

属性

coupon_available_period 　必填 object

【多次优惠可核销时间】确定用户领取多次优惠后在什么时间段内可以核销，多次优惠可核销时间不会超过多次优惠有效天数（多次优惠商品券中配置的 sequential_usage_info.available_days 字段）

属性

available_begin_time 　必填 string

available_end_time 　必填 string

wait_days_after_receive 　选填 integer

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

领券后当天开始生效则无需填写
领券后第二天开始生效则填写 1

weekly_available_period 　选填 object

【每周固定可用时间】每周固定可用时间

属性

day_list 　选填 array[string]

可选取值

MONDAY: 周一可用
TUESDAY: 周二可用
WEDNESDAY: 周三可用
THURSDAY: 周四可用
FRIDAY: 周五可用
SATURDAY: 周六可用
SUNDAY: 周日可用

day_period_list 　选填 array[object]

属性

begin_time 　必填 integer

【当天可用开始时间】当天可用时间距离当天 00:00::00 的秒数，如 60 表示当天 00:01:00 开始可用

end_time 　必填 integer

【当天可用结束时间】当天结束可用时间距离当天 00:00:00 的秒数，如 86399 表示当天 23:59:59 结束可用

irregular_available_period_list 　选填 array[object]

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

属性

normal_coupon_list 　选填 array[object]

【满减券使用规则】当且仅当 type 为 NORMAL 时必填，其他类型不应填写，元素个数应等于 sequential_usage_info.count

属性

threshold 　必填 integer

【门槛金额】使用门槛金额，单位为分，达到该门槛后可享受满减优惠。门槛不得为 0。例如：

满 100 元可用填 10000
满 0.01 元可用填 1

discount_amount 　必填 integer

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

discount_coupon_list 　选填 array[object]

【折扣券使用规则】当且仅当 type 为 DISCOUNT 时必填，其他类型不应填写，元素个数应等于 sequential_usage_info.count

属性

threshold 　必填 integer

【门槛金额】使用门槛金额，单位为分，达到该门槛后可享受折扣优惠。门槛不得为 0。例如：

满 100 元可用填 10000
满 0.01 元可用填 1

percent_off 　必填 integer

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

exchange_coupon_list 　选填 array[object]

【兑换券使用规则】当且仅当 type 为 EXCHANGE 时必填，其他类型不应填写，元素个数应等于 sequential_usage_info.count

属性

threshold 　必填 integer

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

满 100 元可用填 10000
满 0.01 元可用填 1

exchange_price 　必填 integer

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

special_first 　选填 boolean

【多次优惠是否提供首笔特惠】默认情况下为 false，多次优惠各轮优惠力度应保持递增(INCREMENTAL)或等额(EQUAL)。

当此字段设置为 true 时，首轮优惠不受此约束，且必须优于第二轮的优惠力度

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

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

属性

entrance_official_account 　选填 object

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

属性

entrance_finder 　选填 object

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

属性

notify_config 　必填 object

【事件通知配置】发生券相关事件时，微信支付会向品牌方发送通知，需要提供通知相关配置

属性

store_scope 　必填 string

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

可选取值

NONE: 无关联门店，该批次对外不展示可用门店信息
ALL: 所有门店可用，该批次在品牌下的所有门店可用，品牌无需为该批次关联门店列表
SPECIFIC: 特定门店可用，品牌需调用关联门店接口关联门店，关联后该批次在关联的门店可用

sent_count_info 　必填 object

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

属性

state 　必填 string

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

可选取值

AUDITING: 审批中
SENDING: 发放中
PAUSED: 已暂停
STOPPED: 已停止，当前已到达结束时间
DEACTIVATED: 已失效，品牌方主动调用失效接口使批次失效

deactivate_request_no 　选填 string

【失效请求单号】当且仅当 state 为 DEACTIVATED 时提供，返回品牌方调用失效接口时传入的请求流水号

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

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

next_page_token 　选填 string(100)

【下一页Token】分页查询时，如果还有更多数据，会返回下一页的Token，请在下一次查询时设置在 page_token 中；如果已无更多数据，则不返回此字段。

应答示例

200 OK

1{
2  "total_count" : 100,
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      "single_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      "sequential_usage_rule" : {
56        "coupon_available_period" : {
57          "available_begin_time" : "2025-01-01T00:00:00+08:00",
58          "available_end_time" : "2025-10-01T00:00:00+08:00",
59          "wait_days_after_receive" : 1,
60          "weekly_available_period" : {
61            "day_list" : [
62              "MONDAY"
63            ],
64            "day_period_list" : [
65              {
66                "begin_time" : 60,
67                "end_time" : 86399
68              }
69            ]
70          },
71          "irregular_available_period_list" : [
72            {
73              "begin_time" : "2025-01-01T00:00:00+08:00",
74              "end_time" : "2025-10-01T00:00:00+08:00"
75            }
76          ]
77        },
78        "normal_coupon_list" : [
79          {
80            "threshold" : 10000,
81            "discount_amount" : 100
82          }
83        ],
84        "discount_coupon_list" : [
85          {
86            "threshold" : 10000,
87            "percent_off" : 30
88          }
89        ],
90        "exchange_coupon_list" : [
91          {
92            "threshold" : 10000,
93            "exchange_price" : 100
94          }
95        ],
96        "special_first" : false
97      },
98      "usage_rule_display_info" : {
99        "coupon_usage_method_list" : [
100          "MINI_PROGRAM"
101        ],
102        "mini_program_appid" : "wx1234567890",
103        "mini_program_path" : "/pages/index/product",
104        "app_path" : "https://www.example.com/jump-to-app",
105        "usage_description" : "全场可用",
106        "coupon_available_store_info" : {
107          "description" : "可在上海市区的所有门店使用，详细列表参考小程序内信息为准",
108          "mini_program_appid" : "wx1234567890",
109          "mini_program_path" : "/pages/index/store-list"
110        }
111      },
112      "coupon_display_info" : {
113        "code_display_mode" : "QRCODE",
114        "background_color" : "Color010",
115        "entrance_mini_program" : {
116          "appid" : "wx1234567890",
117          "path" : "/pages/index/product",
118          "entrance_wording" : "欢迎选购",
119          "guidance_wording" : "获取更多优惠"
120        },
121        "entrance_official_account" : {
122          "appid" : "wx1234567890"
123        },
124        "entrance_finder" : {
125          "finder_id" : "gh_12345678",
126          "finder_video_id" : "UDFsdf24df34dD456Hdf34",
127          "finder_video_cover_image_url" : "https://wxpaylogo.qpic.cn/wxpaylogo/xxxxx/xxx"
128        }
129      },
130      "notify_config" : {
131        "notify_appid" : "wx4fd12345678"
132      },
133      "store_scope" : "SPECIFIC",
134      "sent_count_info" : {
135        "total_count" : 100,
136        "today_count" : 10
137      },
138      "state" : "SENDING",
139      "deactivate_request_no" : "1002600620019090123143254436",
140      "deactivate_time" : "2025-01-01T00:00+08:00",
141      "deactivate_reason" : "批次信息有误，重新创建"
142    }
143  ],
144  "next_page_token" : "MTIzNDUK"
145}
146

错误码

公共错误码

状态码	错误码	描述	解决方案
400	PARAM_ERROR	参数错误	请根据错误提示正确传入参数
400	INVALID_REQUEST	HTTP 请求不符合微信支付 APIv3 接口规则	请参阅接口规则
401	SIGN_ERROR	验证不通过	请参阅签名常见问题
500	SYSTEM_ERROR	系统异常，请稍后重试	请稍后重试

业务错误码

状态码	错误码	描述	解决方案
403	NO_AUTH	缺少业务相关权限	请确认已开通商品券权限
404	NOT_FOUND	未找到 product_coupon_id 对应的商品券	请确认 product_coupon_id 存在且属于当前品牌
429	RATELIMIT_EXCEEDED	请求超过接口频率限制	请稍后使用原参数重试

文档是否有帮助

更多支持

开发者社区微信开放平台微信公众平台腾讯客服