首页文档中心注册品牌
文档中心
首页文档中心注册品牌
快速开始解决方案产品文档通用规则开发工具
产品文档

添加商品券批次

更新时间：2025.08.28

品牌方可以通过该接口为已有的商品券添加更多批次，多个批次可以实现品牌方多样化的投放需求。

前置条件：已创建商品券

接口说明

支持商户：【品牌商户】

请求方式：【POST】/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

 Content-Type 　必填　string

请设置为application/json

 Wechatpay-Serial 　必填　string

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

path  路径参数

 product_coupon_id 　必填   string

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

body  包体参数

 out_request_no 　必填   string(40)

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

 stock 　必填   object

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

属性

请求示例

POST

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

应答参数

200 OK

 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 时提供，其他场景不提供

属性

 sequential_usage_rule 　选填   object

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

属性

 usage_rule_display_info 　必填   object

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

属性

 coupon_display_info 　必填   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 时提供，返回品牌方调用失效商品券批次接口时传入的失效原因

应答示例

200 OK

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

 

错误码

公共错误码

状态码

错误码

描述

解决方案

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 唯一

403

NO_AUTH

缺少业务相关权限

请确认已开通商品券权限

404

NOT_FOUND

未找到 product_coupon_id 对应的商品券

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

429

RATELIMIT_EXCEEDED

请求超过接口频率限制

请稍后使用原参数重试

 

 

更多支持
开发者社区微信开放平台微信公众平台腾讯客服
接口说明
请求参数
应答参数
错误码
公共错误码
业务错误码
元宝AI开发助手
元宝AI
反馈
目录
置顶
Powered By Tencent & Tenpay Copyright 2005-2025 Tenpay All Rights Reserved.
Powered By Tencent & Tenpay
Copyright 2005-2025 Tenpay All Rights Reserved.