---
url: "https://pay.weixin.qq.com/doc/v3/partner/4015781304.md"
title: "添加商品券批次"
doc_id: 4015781304
---

>更新时间：2025.10.21

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

注：同一个商品券下，最多只能有200个生效中的批次，已过期和已失效的批次不计入统计。

前置条件：商品券处于 `EFFECTIVE` 状态




## 接口说明

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

请求方式：【POST】 `/v3/marketing/partner/product-coupon/product-coupons/{product_coupon_id}/stocks`

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

　　　　　【备域名】https://api2.mch.weixin.qq.com 使用该域名将访问异地的接入点，指引[点击查看](https://pay.weixin.qq.com/doc/v3/merchant/4012075113.md)

接口限频：20/秒（商户号维度）

## 请求参数

### Header 参数
| 参数名 | 类型 | 必填 | 描述 |
| --- |  --- | --- | --- |
| Authorization | string | true | 请参考 [签名认证](https://pay.weixin.qq.com/doc/v3/merchant/4012365342.md#%E8%AF%B7%E6%B1%82%E6%8E%A5%E5%8F%A3%E5%90%8E%E7%AB%AF%E7%AD%BE%E5%90%8D) 生成认证信息 |
| Accept | string | true | 请设置为 `application/json` |
| Content-Type | string | true | 请设置为 `application/json` |
### Path 参数
| 参数名 | 类型 | 必填 | 描述 |
| --- |  --- | --- | --- |
| product_coupon_id | string | true | 【商品券ID】 商品券的唯一标识， [创建商品券](https://pay.weixin.qq.com/doc/v3/partner/4015781289.md) 时由微信支付生成 |
### Body 参数
| 参数名 | 类型 | 必填 | 描述 |
| --- |  --- | --- | --- |
| out_request_no | string(40) | true | 【创建请求单号】 品牌创建批次请求流水号，品牌侧需保持唯一性，可使用 数字、大小写字母、下划线 `_`、短横线 `-` 组成，长度在6-40个字符之间 |
| stock | object | true | 【批次】 为商品券创建的批次详情 |
| stock.remark | string(20) | false | 【备注】 仅配置品牌方可见，用于自定义信息，最多20个UTF-8字符 |
| stock.coupon_code_mode | string | true | 【券Code分配模式】 决定发券时用户商品券Code如何产生<br>可选取值<br><ul><li>`WECHATPAY`:  微信支付随机生成，发券时由微信支付系统自动随机生成券码，品牌方无需干预，微信支付随机生成的券Code长度限制为40个字符以内</li><li>`UPLOAD`:  品牌方预上传Code，品牌方需先使用【 [预上传券Code API(单券)](https://pay.weixin.qq.com/doc/v3/partner/4015781572.md)】或【 [预上传券Code API(多次优惠)](https://pay.weixin.qq.com/doc/v3/partner/4016434668.md)】上传自定义Code，微信支付系统发券时从中随机选取，当预存Code不足时可能影响发券，品牌应及时补充</li><li>`API_ASSIGN`:  品牌方自行指定，品牌方通过【 [向用户发放商品券API](https://pay.weixin.qq.com/doc/v3/partner/4015781605.md)】自行发券时指定，微信支付系统不再进行自动分配。特别注意：这种模式的商品批次只可由品牌方自行发券，无法在摇一摇有优惠等微信支付渠道投放；商品券的 `usage_mode` 为 `PROGRESSIVE_BUNDLE` 时不可使用本模式</li></ul> |
| stock.stock_send_rule | object | true | 【发放规则】 批次的发放规则 |
| stock.stock_send_rule.max_count | integer | true | 【发放次数总上限】 批次在生命周期内总发放次数，最多 100,000,000 次 |
| stock.stock_send_rule.max_count_per_day | integer | false | 【每日发放次数上限】 批次在每天内发放次数上限，每日刷新，最多 100,000,000 次。默认不限制每日发放上限 |
| stock.stock_send_rule.max_count_per_user | integer | true | 【每个用户领取次数上限】 每个用户最多可领取本批次的次数，最多 100 次。 |
| stock.single_usage_rule | object | false | 【单券使用规则】 当且仅当 `usage_mode` 为 `SINGLE` 时必填，其他场景不应填写 |
| stock.single_usage_rule.coupon_available_period | object | true | 【券可核销时间】 确定用户领券后在什么时间段内可以核销 |
| stock.single_usage_rule.coupon_available_period.available_begin_time | string | true | 【批次开始时间】 遵循 [rfc3339标准格式](https://www.rfc-editor.org/rfc/rfc3339.html)，格式为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秒。<br>距离当前创建批次的时间不能超过90天，批次有效期最长不超过365天，摇优惠场景建议设置批次时间大于等于5天 |
| stock.single_usage_rule.coupon_available_period.available_end_time | string | true | 【批次结束时间】 遵循 [rfc3339标准格式](https://www.rfc-editor.org/rfc/rfc3339.html)，格式为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秒。<br>批次有效期最长不超过365天 |
| stock.single_usage_rule.coupon_available_period.available_days | integer | false | 【券生效后N天内可用】 日期区间内，券生效后 N 天内有效，最多365天。例如：<br><ul><li>生效当天内有效填 1</li><li>生效后2天内有效填 2</li><li>依此类推……</li></ul><br>用户在有效期开始前领取商品券，则从有效期第1天开始计算天数，用户在有效期内领取商品券，则从领取当天开始计算天数，无论用户何时领取商品券，商品券在活动有效期结束后均不可用。<br>可配合 `wait_days_after_receive` 一同填写，也可单独填写。<br>注：不可与 `irregular_available_period_list` 同时配置 |
| stock.single_usage_rule.coupon_available_period.wait_days_after_receive | integer | false | 【领券后需等待N天才生效】 日期区间内，用户领券后需等待 N 天才开始生效，最多30天。例如：<br><ul><li>领券后当天开始生效则无需填写</li><li>领券后第二天开始生效则填写 1</li></ul><br>用户在有效期开始前领取商品券，则从有效期第1天开始计算天数，用户在有效期内领取商品券，则从领取当天开始计算天数。无论用户何时领取商品券，商品券在活动有效期结束后均不可用。<br>需配合 `available_days` 一同填写，不可单独填写。<br>注：不可与 `irregular_available_period_list` 同时配置 |
| stock.single_usage_rule.coupon_available_period.weekly_available_period | object | false | 【每周固定可用时间】 日期区间内，每周固定时间可以使用。可与 `available_days` 和 `wait_days_after_receive` 一同配置，一同配置时条件需同时满足券才可用（时间范围取交集）。<br>注：不可与 `irregular_available_period_list` 同时配置 |
| stock.single_usage_rule.coupon_available_period.weekly_available_period.day_list | array[string] | true | 【每周可用星期数】 每周特定星期X可用，在日期区间内每周循环有效。例如 配置 `["MONDAY", "FRIDAY"]` 表示每周一和周五可用。<br>可选取值<br><ul><li>`MONDAY`:  周一可用</li><li>`TUESDAY`:  周二可用</li><li>`WEDNESDAY`:  周三可用</li><li>`THURSDAY`:  周四可用</li><li>`FRIDAY`:  周五可用</li><li>`SATURDAY`:  周六可用</li><li>`SUNDAY`:  周日可用</li></ul> |
| stock.single_usage_rule.coupon_available_period.weekly_available_period.day_period_list | array[object] | false | 【当天可用时间段】 生效当天特定时间段内有效，可以配置多个时间段。最多可以配置 3 个时间段。不配置则全天可用。 |
| stock.single_usage_rule.coupon_available_period.weekly_available_period.day_period_list.begin_time | integer | true | 【当天可用开始时间】 当天可用时间距离当天 00:00:00 的秒数，如 `60` 表示当天 00:01:00 开始可用。取值范围 \[0,86399\] 且必须小于 `end_time` |
| stock.single_usage_rule.coupon_available_period.weekly_available_period.day_period_list.end_time | integer | true | 【当天可用结束时间】 当天结束可用时间距离当天 00:00:00 的秒数，如 `86399` 表示当天 23:59:59 结束可用。取值范围 \[0,86399\] 且必须大于 `begin_time` |
| stock.single_usage_rule.coupon_available_period.irregular_available_period_list | array[object] | false | 【指定可用时间段】 可以配置多个无规律时间段，不同区间内请勿重叠，最多可配置2个区间。<br>注：不可与 `available_days`、 `wait_days_after_receive`、 `weekly_available_period` 同时配置 |
| stock.single_usage_rule.coupon_available_period.irregular_available_period_list.begin_time | string | true | 【开始时间】 区间开始时间，遵循 [rfc3339标准格式](https://www.rfc-editor.org/rfc/rfc3339.html)，格式为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秒。 |
| stock.single_usage_rule.coupon_available_period.irregular_available_period_list.end_time | string | true | 【结束时间】 区间结束时间，遵循 [rfc3339标准格式](https://www.rfc-editor.org/rfc/rfc3339.html)，格式为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秒。 |
| stock.single_usage_rule.coupon_available_period.available_seconds | integer | false | 【领取后N秒内有效】 日期区间内，用户领券后立即生效，自领取时刻起 N 秒内可用，不与自然日对齐。最大为86400（24小时），且仅支持 3600 的整数倍。<br>注：不可与 `available_days`、 `wait_days_after_receive`、 `weekly_available_period`、 `irregular_available_period_list` 同时配置 |
| stock.single_usage_rule.normal_coupon | object | false | 【满减券使用规则】 当且仅当 `type` 为 `NORMAL` 且 `scope` 为 `SINGLE` 时必填，其他类型不应填写 |
| stock.single_usage_rule.normal_coupon.threshold | integer | true | 【门槛金额】 使用门槛金额，单位为分，达到该门槛后可享受满减优惠。门槛可以为0，即无门槛。例如：<br><ul><li>满 100 元可用填 `10000`</li><li>满 0.01 元可用填 `1`</li></ul> |
| stock.single_usage_rule.normal_coupon.discount_amount | integer | true | 【固定减免金额】 固定减免金额，单位为分，必须大于0。 |
| stock.single_usage_rule.discount_coupon | object | false | 【折扣券使用规则】 当且仅当 `type` 为 `DISCOUNT` 且 `scope` 为 `SINGLE` 时必填，其他类型不应填写 |
| stock.single_usage_rule.discount_coupon.threshold | integer | true | 【门槛金额】 使用门槛金额，单位为分，达到该门槛后可享受折扣优惠。门槛可以为0，即无门槛。例如：<br><ul><li>满 100 元可用填 `10000`</li><li>满 0.01 元可用填 `1`</li></ul> |
| stock.single_usage_rule.discount_coupon.percent_off | integer | true | 【固定减免百分比】 表示减免金额为总金额的百分比，必须大于0。例如：填入 `30` 表示减免 30%，即打 7 折 |
| stock.single_usage_rule.exchange_coupon | object | false | 【兑换券使用规则】 当且仅当 `type` 为 `EXCHANGE` 且 `scope` 为 `SINGLE` 时必填，其他类型不应填写 |
| stock.single_usage_rule.exchange_coupon.threshold | integer | true | 【门槛金额】 使用门槛金额，单位为分，达到该门槛后可进行兑换。门槛可以为0，即无门槛兑换。例如：<br><ul><li>满 100 元可用填 `10000`</li><li>满 0.01 元可用填 `1`</li></ul> |
| stock.single_usage_rule.exchange_coupon.exchange_price | integer | true | 【固定兑换价格】 单位为分，必须大于或等于0。 |
| stock.usage_rule_display_info | object | true | 【券使用规则展示信息】 券使用规则展示信息 |
| stock.usage_rule_display_info.coupon_usage_method_list | array[string] | true | 【券使用方式列表】 可以配置多种使用方式<br>可选取值<br><ul><li>`OFFLINE`:  线下滴码核销，点击券“立即使用”跳转展示券二维码详情（投放计划暂不支持此核销方式）</li><li>`MINI_PROGRAM`:  线上小程序核销，点击券“立即使用”跳转至配置的商家小程序（需要添加小程序AppID和Path）</li><li>`APP`:  APP核销，在商家APP内核销</li><li>`PAYMENT_CODE`:  微信支付付款码核销，用户点击券“立即使用”将跳转至微信支付钱包付款码，服务商扫描付款码后可通过付款码获取到用户openid，通过openid查询并核销用户券，核销后再发起下单，适合线下支付场景</li></ul> |
| stock.usage_rule_display_info.mini_program_appid | string | false | 【小程序AppID】 品牌方或服务商小程序AppID，可在微信公众平台查看，该小程序与品牌或服务商存在绑定关系。<br>在 `coupon_usage_method_list` 中包含 `MINI_PROGRAM` 时必填，需和 `mini_program_path` 一同填写。 |
| stock.usage_rule_display_info.mini_program_path | string | false | 【小程序跳转路径】 品牌方或服务商小程序内部跳转路径。<br>在 `coupon_usage_method_list` 中包含 `MINI_PROGRAM` 时必填，需和 `mini_program_appid` 一同填写。 |
| stock.usage_rule_display_info.app_path | string | false | 【APP的H5跳转路径】 品牌方或服务商APP的H5跳转路径。在 `app_jump_type` 为 `H5` 时必填。 |
| stock.usage_rule_display_info.usage_description | string(1000) | true | 【券使用说明】 用于说明详细的券规则，长度不超过1000个UTF-8字符 |
| stock.usage_rule_display_info.coupon_available_store_info | object | false | 【券可用门店信息】 用于描述全部可用门店信息，可配置小程序跳转地址进行展示 |
| stock.usage_rule_display_info.coupon_available_store_info.description | string(1000) | true | 【券可用门店描述】 告知用户本券可在哪些门店使用，长度不超过1000个UTF-8字符 |
| stock.usage_rule_display_info.coupon_available_store_info.mini_program_appid | string | false | 【小程序AppID】 品牌方或服务商小程序AppID，用于展示可用门店列表的详细信息，可在微信公众平台查看，该小程序与品牌或服务商存在绑定关系。需和 `mini_program_path` 一同填写。 |
| stock.usage_rule_display_info.coupon_available_store_info.mini_program_path | string | false | 【小程序跳转路径】 品牌方或服务商小程序内部展示可用门店列表的详细信息的页面跳转路径，需和 `mini_program_appid` 一同填写。 |
| stock.usage_rule_display_info.app_jump_type | string | false | 【APP跳转类型】 APP跳转类型，在 `coupon_usage_method_list` 中包含 `APP` 时必填。<br>可选取值<br><ul><li>`H5`:  跳转H5，点击券立即使用跳转至配置的H5页面</li><li>`PASSCODE_LINK`:  口令链接，点击券立即使用展示口令链接供用户复制使用</li><li>`USAGE_GUIDE`:  展示使用指引，引导前往APP核销</li></ul> |
| stock.usage_rule_display_info.passcode_link | string | false | 【口令链接】 口令链接。在 `app_jump_type` 为 `PASSCODE_LINK` 时必填。 |
| stock.coupon_display_info | object | true | 【用户商品券展示信息】 用户商品券在卡包中的展示详情，包括引导用户的自定义入口 |
| stock.coupon_display_info.code_display_mode | string | true | 【用户商品券Code展示模式】 决定用户商品券Code在卡包中的展示形态<br>可选取值<br><ul><li>`INVISIBLE`:  不展示Code</li><li>`BARCODE`:  条形码</li><li>`QRCODE`:  二维码</li></ul> |
| stock.coupon_display_info.background_color | string | false | 【背景颜色】 券的背景颜色，可设置10种颜色，色值请参考下方说明。颜色取值为颜色图中的颜色名称，不填默认为 `Color020` 。<br>![](https://gtimg.wechatpay.cn/resource/xres/mmpaydoc/static/img/be0dc4f4366fa18064e45fcadb9c7520.png) |
| stock.coupon_display_info.entrance_mini_program | object | false | 【小程序入口】 展示跳转小程序的入口 |
| stock.coupon_display_info.entrance_mini_program.appid | string | true | 【小程序AppID】 品牌方小程序的AppID，可在微信公众平台查看，该小程序与品牌存在绑定关系 |
| stock.coupon_display_info.entrance_mini_program.path | string | true | 【小程序跳转路径】 品牌方小程序内部跳转路径 |
| stock.coupon_display_info.entrance_mini_program.entrance_wording | string(5) | true | 【入口文案】 小程序入口文案，长度不超过5个UTF-8字符 |
| stock.coupon_display_info.entrance_mini_program.guidance_wording | string(6) | true | 【引导文案】 小程序入口引导文案，长度不超过6个UTF-8字符 |
| stock.coupon_display_info.entrance_official_account | object | false | 【公众号入口】 展示跳转公众号的入口 |
| stock.coupon_display_info.entrance_official_account.appid | string | true | 【公众号AppID】 微信公众号唯一标识，可在微信公众平台查看，该公众号应与品牌方存在绑定关系 |
| stock.coupon_display_info.entrance_finder | object | false | 【视频号入口】 展示跳转视频号的入口 |
| stock.coupon_display_info.entrance_finder.finder_id | string | true | 【视频号ID】 关联视频号将展示在优惠券详情的顶部右侧，该视频号应与品牌方存在绑定关系 |
| stock.coupon_display_info.entrance_finder.finder_video_id | string | true | 【视频号视频ID】 券详情视频内容，支持配置关联视频号下的具体视频内容 |
| stock.coupon_display_info.entrance_finder.finder_video_cover_image_url | string | true | 【视频号封面图】 截取的视频号图片将在券到期提醒消息、券详情中展示，仅支持通过【 [图片上传API](https://pay.weixin.qq.com/doc/v3/partner/4015781275.md)】获取的图片URL地址。<br><ul><li>图片尺寸：716像素（宽）\*402像素（高）</li><li>图片大小不超过2M</li><li>建议图片格式：JPG/PNG格式</li></ul> |
| stock.notify_config | object | true | 【事件通知配置】 发生券相关事件时，微信支付会向服务商发送通知，需要提供通知相关配置 |
| stock.notify_config.notify_appid | string | true | 【事件通知AppID】 服务商或者品牌的AppID，支持小程序、服务号、公众号、APP类型的AppID，可在微信公众平台查看，用于券事件通知时计算用户的OpenID，需要与服务商或者品牌存在绑定关系 |
| stock.store_scope | string | true | 【可用门店范围】 控制该批次可以在品牌下哪些门店使用<br>可选取值<br><ul><li>`NONE`:  无关联门店，该批次对外不展示可用门店信息</li><li>`ALL`:  所有门店可用，该批次在品牌下的所有门店可用，品牌无需为该批次关联门店列表</li><li>`SPECIFIC`:  特定门店可用，品牌需调用关联门店接口关联门店，关联后该批次在关联的门店可用</li></ul> |
| brand_id | string | true | 【品牌ID】 微信支付为品牌方分配的唯一标识，该品牌应与服务商存在授权关系 |
## 应答参数

200 OK

| 参数名 | 类型 | 必填 | 描述 |
| --- |  --- | --- | --- |
| product_coupon_id | string(40) | true | 【商品券ID】 商品券的唯一标识，由微信支付生成 |
| stock_id | string(40) | true | 【批次ID】 商品券批次的唯一标识，由微信支付生成 |
| remark | string(20) | false | 【备注】 仅配置品牌可见，用于自定义信息 |
| coupon_code_mode | string | true | 【券Code分配模式】 决定发券时用户商品券Code如何产生<br>可选取值<br><ul><li>`WECHATPAY`:  微信支付随机生成，发券时由微信支付系统自动随机生成券码，品牌方无需干预，微信支付随机生成的券Code长度限制为40个字符以内</li><li>`UPLOAD`:  品牌方预上传Code，品牌方需先使用【 [预上传券Code API(单券)](https://pay.weixin.qq.com/doc/v3/partner/4015781572.md)】或【 [预上传券Code API(多次优惠)](https://pay.weixin.qq.com/doc/v3/partner/4016434668.md)】上传自定义Code，微信支付系统发券时从中随机选取，当预存Code不足时可能影响发券，品牌应及时补充</li><li>`API_ASSIGN`:  品牌方自行指定，品牌方通过【 [向用户发放商品券API](https://pay.weixin.qq.com/doc/v3/partner/4015781605.md)】自行发券时指定，微信支付系统不再进行自动分配。特别注意：这种模式的商品批次只可由品牌方自行发券，无法在摇一摇有优惠等微信支付渠道投放；商品券的 `usage_mode` 为 `PROGRESSIVE_BUNDLE` 时不可使用本模式</li></ul> |
| coupon_code_count_info | object | false | 【品牌方预上传的券Code数量信息】 当且仅当 `coupon_code_mode` 为 `UPLOAD` 时存在此字段 |
| coupon_code_count_info.total_count | integer | true | 【已上传的Code总数】 品牌方为此批次已经上传过的券Code总数量 |
| coupon_code_count_info.available_count | integer | true | 【当前可用的Code数】 品牌方为此批次已经上传过的券Code中，当前剩余可用的券Code数量 |
| stock_send_rule | object | true | 【发放规则】 发放规则 |
| stock_send_rule.max_count | integer | true | 【发放次数总上限】 批次在生命周期内总发放次数，最多 100,000,000 次 |
| stock_send_rule.max_count_per_day | integer | false | 【每日发放次数上限】 批次在每天内发放次数上限，每日刷新，最多 100,000,000 次。默认不限制每日发放上限 |
| stock_send_rule.max_count_per_user | integer | true | 【每个用户领取次数上限】 每个用户最多可领取本批次的次数，最多 100 次。 |
| single_usage_rule | object | false | 【单券使用规则】 当且仅当 `usage_mode` 为 `SINGLE` 时提供，其他场景不提供 |
| single_usage_rule.coupon_available_period | object | true | 【券可核销时间】 确定用户领券后在什么时间段内可以核销 |
| single_usage_rule.coupon_available_period.available_begin_time | string | true | 【批次开始时间】 遵循 [rfc3339标准格式](https://www.rfc-editor.org/rfc/rfc3339.html)，格式为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秒。<br>距离当前创建批次的时间不能超过90天，批次有效期最长不超过365天，摇优惠场景建议设置批次时间大于等于5天 |
| single_usage_rule.coupon_available_period.available_end_time | string | true | 【批次结束时间】 遵循 [rfc3339标准格式](https://www.rfc-editor.org/rfc/rfc3339.html)，格式为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秒。<br>批次有效期最长不超过365天 |
| single_usage_rule.coupon_available_period.available_days | integer | false | 【券生效后N天内可用】 日期区间内，券生效后 N 天内有效，最多365天。例如：<br><ul><li>生效当天内有效填 1</li><li>生效后2天内有效填 2</li><li>依此类推……</li></ul><br>用户在有效期开始前领取商品券，则从有效期第1天开始计算天数，用户在有效期内领取商品券，则从领取当天开始计算天数，无论用户何时领取商品券，商品券在活动有效期结束后均不可用。<br>可配合 `wait_days_after_receive` 一同填写，也可单独填写。<br>注：不可与 `irregular_available_period_list` 同时配置 |
| single_usage_rule.coupon_available_period.wait_days_after_receive | integer | false | 【领券后需等待N天才生效】 日期区间内，用户领券后需等待 N 天才开始生效，最多30天。例如：<br><ul><li>领券后当天开始生效则无需填写</li><li>领券后第二天开始生效则填写 1</li></ul><br>用户在有效期开始前领取商品券，则从有效期第1天开始计算天数，用户在有效期内领取商品券，则从领取当天开始计算天数。无论用户何时领取商品券，商品券在活动有效期结束后均不可用。<br>需配合 `available_days` 一同填写，不可单独填写。<br>注：不可与 `irregular_available_period_list` 同时配置 |
| single_usage_rule.coupon_available_period.weekly_available_period | object | false | 【每周固定可用时间】 日期区间内，每周固定时间可以使用。可与 `available_days` 和 `wait_days_after_receive` 一同配置，一同配置时条件需同时满足券才可用（时间范围取交集）。<br>注：不可与 `irregular_available_period_list` 同时配置 |
| single_usage_rule.coupon_available_period.weekly_available_period.day_list | array[string] | true | 【每周可用星期数】 每周特定星期X可用，在日期区间内每周循环有效。例如 配置 `["MONDAY", "FRIDAY"]` 表示每周一和周五可用。<br>可选取值<br><ul><li>`MONDAY`:  周一可用</li><li>`TUESDAY`:  周二可用</li><li>`WEDNESDAY`:  周三可用</li><li>`THURSDAY`:  周四可用</li><li>`FRIDAY`:  周五可用</li><li>`SATURDAY`:  周六可用</li><li>`SUNDAY`:  周日可用</li></ul> |
| single_usage_rule.coupon_available_period.weekly_available_period.day_period_list | array[object] | false | 【当天可用时间段】 生效当天特定时间段内有效，可以配置多个时间段。最多可以配置 3 个时间段。不配置则全天可用。 |
| single_usage_rule.coupon_available_period.weekly_available_period.day_period_list.begin_time | integer | true | 【当天可用开始时间】 当天可用时间距离当天 00:00:00 的秒数，如 `60` 表示当天 00:01:00 开始可用。取值范围 \[0,86399\] 且必须小于 `end_time` |
| single_usage_rule.coupon_available_period.weekly_available_period.day_period_list.end_time | integer | true | 【当天可用结束时间】 当天结束可用时间距离当天 00:00:00 的秒数，如 `86399` 表示当天 23:59:59 结束可用。取值范围 \[0,86399\] 且必须大于 `begin_time` |
| single_usage_rule.coupon_available_period.irregular_available_period_list | array[object] | false | 【指定可用时间段】 可以配置多个无规律时间段，不同区间内请勿重叠，最多可配置2个区间。<br>注：不可与 `available_days`、 `wait_days_after_receive`、 `weekly_available_period` 同时配置 |
| single_usage_rule.coupon_available_period.irregular_available_period_list.begin_time | string | true | 【开始时间】 区间开始时间，遵循 [rfc3339标准格式](https://www.rfc-editor.org/rfc/rfc3339.html)，格式为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秒。 |
| single_usage_rule.coupon_available_period.irregular_available_period_list.end_time | string | true | 【结束时间】 区间结束时间，遵循 [rfc3339标准格式](https://www.rfc-editor.org/rfc/rfc3339.html)，格式为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秒。 |
| single_usage_rule.coupon_available_period.available_seconds | integer | false | 【领取后N秒内有效】 日期区间内，用户领券后立即生效，自领取时刻起 N 秒内可用，不与自然日对齐。最大为86400（24小时），且仅支持 3600 的整数倍。<br>注：不可与 `available_days`、 `wait_days_after_receive`、 `weekly_available_period`、 `irregular_available_period_list` 同时配置 |
| single_usage_rule.normal_coupon | object | false | 【满减券使用规则】 当且仅当 `type` 为 `NORMAL` 且 `scope` 为 `SINGLE` 时必填，其他类型不应填写 |
| single_usage_rule.normal_coupon.threshold | integer | true | 【门槛金额】 使用门槛金额，单位为分，达到该门槛后可享受满减优惠。门槛可以为0，即无门槛。例如：<br><ul><li>满 100 元可用填 `10000`</li><li>满 0.01 元可用填 `1`</li></ul> |
| single_usage_rule.normal_coupon.discount_amount | integer | true | 【固定减免金额】 固定减免金额，单位为分，必须大于0。 |
| single_usage_rule.discount_coupon | object | false | 【折扣券使用规则】 当且仅当 `type` 为 `DISCOUNT` 且 `scope` 为 `SINGLE` 时必填，其他类型不应填写 |
| single_usage_rule.discount_coupon.threshold | integer | true | 【门槛金额】 使用门槛金额，单位为分，达到该门槛后可享受折扣优惠。门槛可以为0，即无门槛。例如：<br><ul><li>满 100 元可用填 `10000`</li><li>满 0.01 元可用填 `1`</li></ul> |
| single_usage_rule.discount_coupon.percent_off | integer | true | 【固定减免百分比】 表示减免金额为总金额的百分比，必须大于0。例如：填入 `30` 表示减免 30%，即打 7 折 |
| single_usage_rule.exchange_coupon | object | false | 【兑换券使用规则】 当且仅当 `type` 为 `EXCHANGE` 且 `scope` 为 `SINGLE` 时必填，其他类型不应填写 |
| single_usage_rule.exchange_coupon.threshold | integer | true | 【门槛金额】 使用门槛金额，单位为分，达到该门槛后可进行兑换。门槛可以为0，即无门槛兑换。例如：<br><ul><li>满 100 元可用填 `10000`</li><li>满 0.01 元可用填 `1`</li></ul> |
| single_usage_rule.exchange_coupon.exchange_price | integer | true | 【固定兑换价格】 单位为分，必须大于或等于0。 |
| usage_rule_display_info | object | true | 【券使用规则展示信息】 券使用规则展示信息 |
| usage_rule_display_info.coupon_usage_method_list | array[string] | true | 【券使用方式列表】 可以配置多种使用方式<br>可选取值<br><ul><li>`OFFLINE`:  线下滴码核销，点击券“立即使用”跳转展示券二维码详情（投放计划暂不支持此核销方式）</li><li>`MINI_PROGRAM`:  线上小程序核销，点击券“立即使用”跳转至配置的商家小程序（需要添加小程序AppID和Path）</li><li>`APP`:  APP核销，在商家APP内核销</li><li>`PAYMENT_CODE`:  微信支付付款码核销，用户点击券“立即使用”将跳转至微信支付钱包付款码，服务商扫描付款码后可通过付款码获取到用户openid，通过openid查询并核销用户券，核销后再发起下单，适合线下支付场景</li></ul> |
| usage_rule_display_info.mini_program_appid | string | false | 【小程序AppID】 品牌方或服务商小程序AppID，可在微信公众平台查看，该小程序与品牌或服务商存在绑定关系。<br>在 `coupon_usage_method_list` 中包含 `MINI_PROGRAM` 时必填，需和 `mini_program_path` 一同填写。 |
| usage_rule_display_info.mini_program_path | string | false | 【小程序跳转路径】 品牌方或服务商小程序内部跳转路径。<br>在 `coupon_usage_method_list` 中包含 `MINI_PROGRAM` 时必填，需和 `mini_program_appid` 一同填写。 |
| usage_rule_display_info.app_path | string | false | 【APP的H5跳转路径】 品牌方或服务商APP的H5跳转路径。在 `app_jump_type` 为 `H5` 时必填。 |
| usage_rule_display_info.usage_description | string(1000) | true | 【券使用说明】 用于说明详细的券规则，长度不超过1000个UTF-8字符 |
| usage_rule_display_info.coupon_available_store_info | object | false | 【券可用门店信息】 用于描述全部可用门店信息，可配置小程序跳转地址进行展示 |
| usage_rule_display_info.coupon_available_store_info.description | string(1000) | true | 【券可用门店描述】 告知用户本券可在哪些门店使用，长度不超过1000个UTF-8字符 |
| usage_rule_display_info.coupon_available_store_info.mini_program_appid | string | false | 【小程序AppID】 品牌方或服务商小程序AppID，用于展示可用门店列表的详细信息，可在微信公众平台查看，该小程序与品牌或服务商存在绑定关系。需和 `mini_program_path` 一同填写。 |
| usage_rule_display_info.coupon_available_store_info.mini_program_path | string | false | 【小程序跳转路径】 品牌方或服务商小程序内部展示可用门店列表的详细信息的页面跳转路径，需和 `mini_program_appid` 一同填写。 |
| usage_rule_display_info.app_jump_type | string | false | 【APP跳转类型】 APP跳转类型，在 `coupon_usage_method_list` 中包含 `APP` 时必填。<br>可选取值<br><ul><li>`H5`:  跳转H5，点击券立即使用跳转至配置的H5页面</li><li>`PASSCODE_LINK`:  口令链接，点击券立即使用展示口令链接供用户复制使用</li><li>`USAGE_GUIDE`:  展示使用指引，引导前往APP核销</li></ul> |
| usage_rule_display_info.passcode_link | string | false | 【口令链接】 口令链接。在 `app_jump_type` 为 `PASSCODE_LINK` 时必填。 |
| coupon_display_info | object | true | 【用户商品券展示信息】 用户商品券在卡包中的展示详情，包括引导用户的自定义入口 |
| coupon_display_info.code_display_mode | string | true | 【用户商品券Code展示模式】 决定用户商品券Code在卡包中的展示形态<br>可选取值<br><ul><li>`INVISIBLE`:  不展示Code</li><li>`BARCODE`:  条形码</li><li>`QRCODE`:  二维码</li></ul> |
| coupon_display_info.background_color | string | false | 【背景颜色】 券的背景颜色，可设置10种颜色，色值请参考下方说明。颜色取值为颜色图中的颜色名称，不填默认为 `Color020` 。<br>![](https://gtimg.wechatpay.cn/resource/xres/mmpaydoc/static/img/be0dc4f4366fa18064e45fcadb9c7520.png) |
| coupon_display_info.entrance_mini_program | object | false | 【小程序入口】 展示跳转小程序的入口 |
| coupon_display_info.entrance_mini_program.appid | string | true | 【小程序AppID】 品牌方小程序的AppID，可在微信公众平台查看，该小程序与品牌存在绑定关系 |
| coupon_display_info.entrance_mini_program.path | string | true | 【小程序跳转路径】 品牌方小程序内部跳转路径 |
| coupon_display_info.entrance_mini_program.entrance_wording | string(5) | true | 【入口文案】 小程序入口文案，长度不超过5个UTF-8字符 |
| coupon_display_info.entrance_mini_program.guidance_wording | string(6) | true | 【引导文案】 小程序入口引导文案，长度不超过6个UTF-8字符 |
| coupon_display_info.entrance_official_account | object | false | 【公众号入口】 展示跳转公众号的入口 |
| coupon_display_info.entrance_official_account.appid | string | true | 【公众号AppID】 微信公众号唯一标识，可在微信公众平台查看，该公众号应与品牌方存在绑定关系 |
| coupon_display_info.entrance_finder | object | false | 【视频号入口】 展示跳转视频号的入口 |
| coupon_display_info.entrance_finder.finder_id | string | true | 【视频号ID】 关联视频号将展示在优惠券详情的顶部右侧，该视频号应与品牌方存在绑定关系 |
| coupon_display_info.entrance_finder.finder_video_id | string | true | 【视频号视频ID】 券详情视频内容，支持配置关联视频号下的具体视频内容 |
| coupon_display_info.entrance_finder.finder_video_cover_image_url | string | true | 【视频号封面图】 截取的视频号图片将在券到期提醒消息、券详情中展示，仅支持通过【 [图片上传API](https://pay.weixin.qq.com/doc/v3/partner/4015781275.md)】获取的图片URL地址。<br><ul><li>图片尺寸：716像素（宽）\*402像素（高）</li><li>图片大小不超过2M</li><li>建议图片格式：JPG/PNG格式</li></ul> |
| notify_config | object | true | 【事件通知配置】 发生券相关事件时，微信支付会向服务商发送通知，需要提供通知相关配置 |
| notify_config.notify_appid | string | true | 【事件通知AppID】 服务商或者品牌的AppID，支持小程序、服务号、公众号、APP类型的AppID，可在微信公众平台查看，用于券事件通知时计算用户的OpenID，需要与服务商或者品牌存在绑定关系 |
| store_scope | string | true | 【可用门店范围】 控制该批次可以在品牌下哪些门店使用<br>可选取值<br><ul><li>`NONE`:  无关联门店，该批次对外不展示可用门店信息</li><li>`ALL`:  所有门店可用，该批次在品牌下的所有门店可用，品牌无需为该批次关联门店列表</li><li>`SPECIFIC`:  特定门店可用，品牌需调用关联门店接口关联门店，关联后该批次在关联的门店可用</li></ul> |
| sent_count_info | object | true | 【已发放次数】 本批次已发放次数 |
| sent_count_info.total_count | integer | true | 【已发放总次数】 批次在生命周期内已发放次数 |
| sent_count_info.today_count | integer | true | 【当天已发放次数】 批次在当天已发放次数 |
| state | string | true | 【批次状态】 商品券批次状态<br>可选取值<br><ul><li>`AUDITING`:  审批中</li><li>`SENDING`:  发放中</li><li>`PAUSED`:  已暂停</li><li>`STOPPED`:  已停止，当前已到达结束时间</li><li>`DEACTIVATED`:  已失效，品牌方主动调用失效接口使批次失效</li></ul> |
| deactivate_request_no | string(128) | false | 【失效请求单号】 当且仅当 `state` 为 `DEACTIVATED` 时提供，返回品牌方调用失效接口时传入的请求流水号 |
| deactivate_time | string | false | 【失效时间】 当且仅当 `state` 为 `DEACTIVATED` 时提供，遵循 [rfc3339标准格式](https://www.rfc-editor.org/rfc/rfc3339.html)，格式为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) | false | 【失效原因】 当且仅当 `state` 为 `DEACTIVATED` 时提供，返回品牌方调用【 [失效商品券批次API](https://pay.weixin.qq.com/doc/v3/partner/4015781532.md)】时传入的失效原因 |
| brand_id | string | true | 【品牌ID】 微信支付为品牌方分配的唯一标识，该品牌应与服务商存在授权关系 |
## 错误码

以下是本接口返回的错误码列表。详细错误码规则，请参考[微信支付接口规则-错误码和错误提示](https://pay.weixin.qq.com/doc/v3/partner/4012081726.md#%E9%94%99%E8%AF%AF%E7%A0%81%E5%92%8C%E9%94%99%E8%AF%AF%E6%8F%90%E7%A4%BA)

| 状态码 | 错误码 | 描述 | 解决方案 |
| --- | --- | --- | --- |
| 400 | PARAM\_ERROR | 参数错误 | 请根据错误提示正确传入参数 |
| 400 | INVALID\_REQUEST | HTTP 请求不符合微信支付 APIv3 接口规则 | 请参阅 [接口规则](https://pay.weixin.qq.com/doc/v3/merchant/4012081709.md) |
| 401 | SIGN\_ERROR | 验证不通过 | 请参阅 [签名常见问题](https://pay.weixin.qq.com/doc/v3/merchant/4012072670.md) |
| 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 | 请求超过接口频率限制 | 请稍后使用原参数重试 |

请求示例

- [curl 示例](https://pay.weixin.qq.com/doc/v3/partner/4015781304-curl.md)
- [Java 示例](https://pay.weixin.qq.com/doc/v3/partner/4015781304-java.md)
- [Go 示例](https://pay.weixin.qq.com/doc/v3/partner/4015781304-go.md)


应答示例

> 200 OK

为满100可用的全场8折券添加批次

```
{
  "product_coupon_id" : "1000000013",
  "stock_id" : "1000000013001",
  "remark" : "8月工作日有效批次",
  "coupon_code_mode" : "UPLOAD",
  "coupon_code_count_info" : {
    "total_count" : 0,
    "available_count" : 0
  },
  "stock_send_rule" : {
    "max_count" : 10000000,
    "max_count_per_user" : 1
  },
  "single_usage_rule" : {
    "coupon_available_period" : {
      "available_begin_time" : "2025-08-01T00:00:00+08:00",
      "available_end_time" : "2025-08-31T23:59:59+08:00",
      "available_days" : 30,
      "weekly_available_period" : {
        "day_list" : [
          "MONDAY",
          "TUESDAY",
          "WEDNESDAY",
          "THURSDAY",
          "FRIDAY"
        ]
      }
    }
  },
  "usage_rule_display_info" : {
    "coupon_usage_method_list" : [
      "OFFLINE",
      "MINI_PROGRAM",
      "PAYMENT_CODE"
    ],
    "mini_program_appid" : "wx1234567890",
    "mini_program_path" : "/pages/index/product",
    "usage_description" : "工作日可用",
    "coupon_available_store_info" : {
      "description" : "所有门店可用，可使用小程序查看门店列表",
      "mini_program_appid" : "wx1234567890",
      "mini_program_path" : "/pages/index/store-list"
    }
  },
  "coupon_display_info" : {
    "code_display_mode" : "QRCODE",
    "background_color" : "Color010",
    "entrance_mini_program" : {
      "appid" : "wx1234567890",
      "path" : "/pages/index/product",
      "entrance_wording" : "欢迎选购",
      "guidance_wording" : "获取更多优惠"
    },
    "entrance_official_account" : {
      "appid" : "wx1234567890"
    },
    "entrance_finder" : {
      "finder_id" : "gh_12345678",
      "finder_video_id" : "UDFsdf24df34dD456Hdf34",
      "finder_video_cover_image_url" : "https://wxpaylogo.qpic.cn/wxpaylogo/xxxxx/xxx"
    }
  },
  "notify_config" : {
    "notify_appid" : "wx4fd12345678"
  },
  "store_scope" : "NONE",
  "sent_count_info" : {
    "total_count" : 0,
    "today_count" : 0
  },
  "state" : "SENDING",
  "brand_id" : "120344"
}

```
