---
url: "https://pay.weixin.qq.com/doc/brand/4016427409.md"
title: "退券"
doc_id: 4016427409
---

>更新时间：2025.11.06

品牌方可以通过本接口将已经核销用户的商品券退回给用户。

前置条件：已经给用户发券成功，且用户商品券当前已核销




## 接口说明

支持商户：【品牌商户】

请求方式：【POST】 `/brand/marketing/product-coupon/users/{openid}/coupons/{coupon_code}/return`

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

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

接口限频：500/秒（品牌ID维度）

## 请求参数

### Header 参数
| 参数名 | 类型 | 必填 | 描述 |
| --- |  --- | --- | --- |
| Authorization | string | true | 请参考 [签名认证](https://pay.weixin.qq.com/doc/brand/4015407568.md) 生成认证信息 |
| Accept | string | true | 请设置为 `application/json` |
| Content-Type | string | true | 请设置为 `application/json` |
| Wechatpay-Serial | string | true | 【微信支付公钥ID】  请传入brand\_id对应的微信支付公钥ID，接口将会校验两者的关联关系，参考 [微信支付公钥产品简介及使用说明](https://pay.weixin.qq.com/doc/brand/4015597001.md) 获取微信支付公钥ID和相关的介绍。以下两种场景将使用到微信支付公钥：<br>1、接收到接口的返回内容，需要使用微信支付公钥进行验签；<br>2、调用含有敏感信息参数（如姓名、身份证号码）的接口时，需要使用微信支付公钥加密敏感信息后再传输参数，加密指引请参考 [微信支付公钥加密敏感信息指引](https://pay.weixin.qq.com/doc/brand/4015407587.md)。 |
### Path 参数
| 参数名 | 类型 | 必填 | 描述 |
| --- |  --- | --- | --- |
| coupon_code | string(40) | true | 【用户商品券Code】 用户商品券的唯一标识 |
| openid | string | true | 【用户OpenID】 OpenID信息，用户在AppID下的唯一标识，获取方式参考 [OpenID](https://pay.weixin.qq.com/doc/brand/4015407536.md#OpenID) |
### Body 参数
| 参数名 | 类型 | 必填 | 描述 |
| --- |  --- | --- | --- |
| product_coupon_id | string | true | 【商品券ID】 商品券的唯一标识， [创建商品券](https://pay.weixin.qq.com/doc/brand/4015736297.md) 时由微信支付生成 |
| stock_id | string | true | 【批次ID】 商品券批次的唯一标识，商品券批次创建时由微信支付生成（可使用【 [创建商品券API](https://pay.weixin.qq.com/doc/brand/4015736297.md)】或【 [添加商品券批次API](https://pay.weixin.qq.com/doc/brand/4015736342.md)】创建），请确保该批次属于 `product_coupon_id` 对应的商品券 |
| appid | string | true | 【公众账号ID】 公众账号ID也称AppID，是（微信开放平台、微信公众平台）为开发者提供的一个唯一标识，用于识别开发者的应用程序(APP、小程序、公众号)。 开发者需要先在微信开放平台或微信公众平台中申请ID，然后在品牌经营平台中绑定，详见 [品牌经营平台指引](https://doc.weixin.qq.com/doc/w3_AUMA3AbsAKcCNqNE3jV15S96SGeWR?scode=AJEAIQdfAAo0BPGyi6AUMA3AbsAKc)。 |
| out_request_no | string(40) | true | 【退券请求单号】 品牌退用户商品券的请求流水号，品牌侧需保持唯一性，可使用 数字、大小写字母、下划线 `_`、短横线 `-` 组成，长度在6-40个字符之间 |
## 应答参数

200 OK

| 参数名 | 类型 | 必填 | 描述 |
| --- |  --- | --- | --- |
| coupon_code | string(40) | true | 【用户商品券Code】 用户商品券的唯一标识 |
| coupon_state | string | true | 【用户商品券状态】<br>可选取值<br><ul><li>`CONFIRMING`:  待确认，用户商品券发放需要品牌方调用【 [确认发放用户商品券API(单券)](https://pay.weixin.qq.com/doc/brand/4015736403.md)】或【 [确认发放用户商品券API(多次优惠)](https://pay.weixin.qq.com/doc/brand/4016427390.md)】后才能生效</li><li>`PENDING`:  已发放待生效，用户商品券已发放成功但尚未到达可用开始时间</li><li>`EFFECTIVE`:  已生效，用户商品券已成功发放且到达可用开始时间</li><li>`USED`:  已核销，用户商品券已核销</li><li>`EXPIRED`:  已过期，用户商品券已超过有效期，不再可用</li><li>`DELETED`:  已删除，用户主动删除该券</li><li>`DEACTIVATED`:  已失效，品牌方主动调用【 [失效用户商品券API](https://pay.weixin.qq.com/doc/brand/4015736411.md)】或【 [失效用户商品券组API](https://pay.weixin.qq.com/doc/brand/4016279743.md)】使用户商品券失效</li></ul> |
| valid_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小时，即北京时间） |
| valid_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小时，即北京时间） |
| receive_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小时，即北京时间） |
| send_request_no | string(128) | true | 【发券请求单号】 发券时传入的请求流水号 |
| send_channel | string | true | 【发券渠道】 描述用户商品券是经由什么渠道发送的<br>可选取值<br><ul><li>`BRAND_MANAGE`:  摇一摇有优惠，通过摇一摇有优惠渠道发放</li><li>`API`:  品牌方自主发券，品牌方通过发券接口自主发券到商家名片</li><li>`RECEIVE_COMPONENT`:  小程序领券组件，品牌方通过小程序领券组件发券</li></ul> |
| confirm_request_no | string | false | 【确认请求单号】 品牌方确认发券请求时传入的的请求流水号。当且仅当 品牌方调用【 [确认发放用户商品券API](https://pay.weixin.qq.com/doc/brand/4015736403.md)】后提供。 |
| confirm_time | string | false | 【确认发放时间】 品牌方确认发券时间，当且仅当 品牌方调用【 [确认发放用户商品券API](https://pay.weixin.qq.com/doc/brand/4015736403.md)】后提供。遵循 [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小时，即北京时间） |
| deactivate_request_no | string(128) | false | 【失效请求单号】 品牌方失效券请求时传入的的请求流水号。当且仅当 `coupon_state` 为 `DEACTIVATED` 时提供，返回品牌方调用【 [失效用户商品券API](https://pay.weixin.qq.com/doc/brand/4015736411.md)】或【 [失效用户商品券组API](https://pay.weixin.qq.com/doc/brand/4016279743.md)】时传入的请求流水号 |
| deactivate_time | string | false | 【失效时间】 失效时间，当且仅当 `coupon_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小时，即北京时间） |
| deactivate_reason | string(150) | false | 【失效原因】 失效券的原因，当且仅当 `coupon_state` 为 `DEACTIVATED` 时提供，返回品牌方调用【 [失效用户商品券API](https://pay.weixin.qq.com/doc/brand/4015736411.md)】或【 [失效用户商品券组API](https://pay.weixin.qq.com/doc/brand/4016279743.md)】时传入的失效原因 |
| single_usage_detail | object | false | 【单券使用详情】 当且仅当 `usage_mode` 为 `SINGLE` 时提供 |
| single_usage_detail.use_request_no | string | false | 【券核销请求单号】 券核销的请求流水号，当且仅当用户商品券状态 `coupon_state` 为 `USED` 时提供 |
| single_usage_detail.use_time | string | false | 【券核销时间】 券被核销的时间，当且仅当用户商品券状态 `coupon_state` 为 `USED` 时提供。遵循 [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小时，即北京时间） |
| single_usage_detail.return_request_no | string | false | 【退券请求单号】 品牌退券时传入的请求流水号，当且仅当券发生了退回后提供此字段 |
| single_usage_detail.return_time | string | false | 【退券时间】 券被退回的时间，当且仅当券发生了退回后提供此字段。遵循 [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小时，即北京时间） |
| single_usage_detail.associated_order_info | object | false | 【券核销的微信支付订单信息】 券核销对应的微信支付订单信息，当且仅当用户商品券状态 `coupon_state` 为 `USED` 时提供,<br>注:<br>1、 `associated_order_info` 与 `associated_pay_score_order_info` 会根据核销请求时的传入参数决定返回对应字段<br>2、订单信息必须至少传入 `transaction_id` 与 `out_trade_no` 之一，亦可同时传入，同时传入时应保证二者指向同一笔微信支付单。 |
| single_usage_detail.associated_order_info.transaction_id | string | false | 【微信支付单号】 由微信支付生成的支付单唯一标识，可以唯一定位到一笔微信支付单。<br>注：订单信息必须至少传入 `transaction_id` 与 `out_trade_no` 之一，亦可同时传入，同时传入时应保证二者指向同一笔微信支付单。 |
| single_usage_detail.associated_order_info.out_trade_no | string | false | 【商户订单号】 在微信支付支付时传入的商户订单号，在商户侧具有唯一性，因此提供此字段时应同时提供下单商户号：<br><ul><li>如果此单为服务商模式下单，则需提供 父商户号 `mchid` 以及 子商户号 `sub_mchid`</li><li>如果此单为直连商户模式下单，则需提供 直连商户号 `mchid`</li></ul><br>注：订单信息必须至少传入 `transaction_id` 与 `out_trade_no` 之一，亦可同时传入，同时传入时应保证二者指向同一笔微信支付单。 |
| single_usage_detail.associated_order_info.mchid | string | false | 【商户号】 当提供 `out_trade_no` 时此字段必传，否则可以省略。参考如下规则传入：<br><ul><li>若为服务商模式，则此字段为服务商商户号</li><li>若为直连商户模式，则此字段为商户号</li></ul> |
| single_usage_detail.associated_order_info.sub_mchid | string | false | 【子商户号】 当提供 `out_trade_no` 时，参考如下规则传入：<br><ul><li>若为服务商模式，则此字段必填，为子商户号</li><li>若为直连商户模式，则此字段为空</li></ul><br>不提供 `out_trade_no` 时可忽略此字段 |
| single_usage_detail.associated_pay_score_order_info | object | false | 【券核销的关联微信支付分订单信息】 券核销的关联微信支付分订单信息，当且仅当用户商品券状态 `coupon_state` 为 `USED` 时提供,<br>注:<br>1、 `associated_order_info` 与 `associated_pay_score_order_info` 会根据核销请求时的传入参数决定返回对应字段<br>2、订单信息必须至少传入 `order_id` 与 `out_order_no` 之一，亦可同时传入，同时传入时应保证二者指向同一笔微信支付单。 |
| single_usage_detail.associated_pay_score_order_info.order_id | string | false | 【微信支付服务订单号】 支付分订单在微信侧的唯一标识。<br>注：订单信息必须至少传入 `order_id` 与 `out_order_no` 之一，亦可同时传入，同时传入时应保证二者指向同一笔微信支付单。 |
| single_usage_detail.associated_pay_score_order_info.out_order_no | string | false | 【商户服务订单号】 商户系统内部服务订单号，要求32个字符内，只能是数字、大小写字母\_-&#124; 且在同一个商户号下唯一。：<br><ul><li>如果此单为服务商模式下单，则需提供 父商户号 `mchid` 以及 子商户号 `sub_mchid`</li><li>如果此单为直连商户模式下单，则需提供 直连商户号 `mchid`</li></ul><br>注：订单信息必须至少传入 `order_id` 与 `out_order_no` 之一，亦可同时传入，同时传入时应保证二者指向同一笔微信支付服务单。 |
| single_usage_detail.associated_pay_score_order_info.mchid | string | false | 【商户号】 当提供 `out_order_no` 时此字段必传，否则可以省略。参考如下规则传入：<br><ul><li>若为服务商模式，则此字段为服务商商户号</li><li>若为直连商户模式，则此字段为商户号</li></ul> |
| single_usage_detail.associated_pay_score_order_info.sub_mchid | string | false | 【子商户号】 当提供 `out_order_no` 时，参考如下规则传入：<br><ul><li>若为服务商模式，则此字段必填，为子商户号</li><li>若为直连商户模式，则此字段为空</li></ul><br>不提供 `out_order_no` 时可忽略此字段 |
| single_usage_detail.saved_amount | integer | false | 【优惠金额】 使用本券的实际优惠金额，单位为分<br>注：<br><ul><li>当本券为全场/品类折扣券（scope= `ALL` 或 `CATEGORY`）时，提供的是商户传入的值</li></ul> |
| progressive_bundle_usage_detail | object | false | 【多次优惠使用详情】 当且仅当 `usage_mode` 为 `PROGRESSIVE_BUNDLE` 时提供 |
| progressive_bundle_usage_detail.use_request_no | string | false | 【券核销请求单号】 券核销的请求流水号，当且仅当用户商品券状态 `coupon_state` 为 `USED` 时提供 |
| progressive_bundle_usage_detail.use_time | string | false | 【券核销时间】 券被核销的时间，当且仅当用户商品券状态 `coupon_state` 为 `USED` 时提供。遵循 [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小时，即北京时间） |
| progressive_bundle_usage_detail.return_request_no | string | false | 【退券请求单号】 品牌退券时传入的请求流水号，当且仅当券发生了退回后提供此字段 |
| progressive_bundle_usage_detail.return_time | string | false | 【退券时间】 券被退回的时间，当且仅当券发生了退回后提供此字段。遵循 [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小时，即北京时间） |
| progressive_bundle_usage_detail.associated_order_info | object | false | 【券核销的微信支付订单信息】 券核销对应的微信支付订单信息，当且仅当用户商品券状态 `coupon_state` 为 `USED` 时提供,<br>注:<br>1、 `associated_order_info` 与 `associated_pay_score_order_info` 会根据核销请求时的传入参数决定返回对应字段<br>2、订单信息必须至少传入 `transaction_id` 与 `out_trade_no` 之一，亦可同时传入，同时传入时应保证二者指向同一笔微信支付单。 |
| progressive_bundle_usage_detail.associated_order_info.transaction_id | string | false | 【微信支付单号】 由微信支付生成的支付单唯一标识，可以唯一定位到一笔微信支付单。<br>注：订单信息必须至少传入 `transaction_id` 与 `out_trade_no` 之一，亦可同时传入，同时传入时应保证二者指向同一笔微信支付单。 |
| progressive_bundle_usage_detail.associated_order_info.out_trade_no | string | false | 【商户订单号】 在微信支付支付时传入的商户订单号，在商户侧具有唯一性，因此提供此字段时应同时提供下单商户号：<br><ul><li>如果此单为服务商模式下单，则需提供 父商户号 `mchid` 以及 子商户号 `sub_mchid`</li><li>如果此单为直连商户模式下单，则需提供 直连商户号 `mchid`</li></ul><br>注：订单信息必须至少传入 `transaction_id` 与 `out_trade_no` 之一，亦可同时传入，同时传入时应保证二者指向同一笔微信支付单。 |
| progressive_bundle_usage_detail.associated_order_info.mchid | string | false | 【商户号】 当提供 `out_trade_no` 时此字段必传，否则可以省略。参考如下规则传入：<br><ul><li>若为服务商模式，则此字段为服务商商户号</li><li>若为直连商户模式，则此字段为商户号</li></ul> |
| progressive_bundle_usage_detail.associated_order_info.sub_mchid | string | false | 【子商户号】 当提供 `out_trade_no` 时，参考如下规则传入：<br><ul><li>若为服务商模式，则此字段必填，为子商户号</li><li>若为直连商户模式，则此字段为空</li></ul><br>不提供 `out_trade_no` 时可忽略此字段 |
| progressive_bundle_usage_detail.associated_pay_score_order_info | object | false | 【券核销的关联微信支付分订单信息】 券核销的关联微信支付分订单信息，当且仅当用户商品券状态 `coupon_state` 为 `USED` 时提供,<br>注:<br>1、 `associated_order_info` 与 `associated_pay_score_order_info` 会根据核销请求时的传入参数决定返回对应字段<br>2、订单信息必须至少传入 `order_id` 与 `out_order_no` 之一，亦可同时传入，同时传入时应保证二者指向同一笔微信支付单。 |
| progressive_bundle_usage_detail.associated_pay_score_order_info.order_id | string | false | 【微信支付服务订单号】 支付分订单在微信侧的唯一标识。<br>注：订单信息必须至少传入 `order_id` 与 `out_order_no` 之一，亦可同时传入，同时传入时应保证二者指向同一笔微信支付单。 |
| progressive_bundle_usage_detail.associated_pay_score_order_info.out_order_no | string | false | 【商户服务订单号】 商户系统内部服务订单号，要求32个字符内，只能是数字、大小写字母\_-&#124; 且在同一个商户号下唯一。：<br><ul><li>如果此单为服务商模式下单，则需提供 父商户号 `mchid` 以及 子商户号 `sub_mchid`</li><li>如果此单为直连商户模式下单，则需提供 直连商户号 `mchid`</li></ul><br>注：订单信息必须至少传入 `order_id` 与 `out_order_no` 之一，亦可同时传入，同时传入时应保证二者指向同一笔微信支付服务单。 |
| progressive_bundle_usage_detail.associated_pay_score_order_info.mchid | string | false | 【商户号】 当提供 `out_order_no` 时此字段必传，否则可以省略。参考如下规则传入：<br><ul><li>若为服务商模式，则此字段为服务商商户号</li><li>若为直连商户模式，则此字段为商户号</li></ul> |
| progressive_bundle_usage_detail.associated_pay_score_order_info.sub_mchid | string | false | 【子商户号】 当提供 `out_order_no` 时，参考如下规则传入：<br><ul><li>若为服务商模式，则此字段必填，为子商户号</li><li>若为直连商户模式，则此字段为空</li></ul><br>不提供 `out_order_no` 时可忽略此字段 |
| progressive_bundle_usage_detail.saved_amount | integer | false | 【优惠金额】 使用本券的实际优惠金额，单位为分<br>注：<br><ul><li>当本券为全场/品类折扣券（scope= `ALL` 或 `CATEGORY`）时，提供的是商户传入的值</li></ul> |
| user_product_coupon_bundle_info | object | false | 【用户券组信息】 当前用户券所属用户券组的信息，当且仅当 `usage_mode` 为 `PROGRESSIVE_BUNDLE` 时提供 |
| user_product_coupon_bundle_info.user_coupon_bundle_id | string | true | 【用户券组ID】 本券所属的用户券组ID，【 [向用户发放商品券批次组](https://pay.weixin.qq.com/doc/brand/4016279745.md)】时由微信支付生成 |
| user_product_coupon_bundle_info.user_coupon_bundle_index | integer | true | 【用户券组内索引】 本券在所属用户券组内的序号，从 0 开始编号 |
| user_product_coupon_bundle_info.total_count | integer | true | 【总可使用次数】 所属用户券组总计可用次数 |
| user_product_coupon_bundle_info.used_count | integer | true | 【已使用次数】 所属用户券组已使用次数 |
| product_coupon | object | true | 【商品券信息】 该用户商品券对应的商品券详情 |
| product_coupon.product_coupon_id | string(40) | true | 【商品券ID】 商品券的唯一标识，由微信支付生成 |
| product_coupon.scope | string | true | 【优惠范围】 商品券优惠范围<br>可选取值<br><ul><li>`ALL`:  全场商品可用券，此时券类型 `type` 仅可配置为 `NORMAL` 或 `DISCOUNT`</li><li>`SINGLE`:  部分商品可用券，此时券类型 `type` 配置不受限制，即可配置为 `NORMAL`、 `DISCOUNT` 或 `EXCHANGE`</li><li>`CATEGORY`:  品类券。适用于商户对某一品类商品提供优惠的场景；系统侧不维护商品/品类清单，具体可用商品范围由商户在 `display_info` 描述、图片等字段中向用户告知，并在核销时由商户自行判定。此时券类型 `type` 仅可配置为 `NORMAL` 或 `DISCOUNT`</li></ul> |
| product_coupon.type | string | true | 【商品券类型】 商品券的优惠类型<br>可选取值<br><ul><li>`NORMAL`:  满减券</li><li>`DISCOUNT`:  折扣券</li><li>`EXCHANGE`:  兑换券，仅在 `scope` 为 `SINGLE` 时可配置</li></ul> |
| product_coupon.usage_mode | string | true | 【使用模式】 商品券使用模式<br>可选取值<br><ul><li>`SINGLE`:  单券，即用户只能使用一次，使用后券失效</li><li>`PROGRESSIVE_BUNDLE`:  多次优惠，由一组批次组成，每阶梯次序对应一个批次。用户按顺序使用，每次核销后发放下一张券，直到用完为止</li></ul> |
| product_coupon.single_usage_info | object | false | 【单券模式信息】 单券模式配置信息，仅当 `usage_mode` 为 `SINGLE` 时提供，其他场景不提供。 |
| product_coupon.single_usage_info.normal_coupon | object | false | 【满减券使用规则】 本商品券内所有批次均以此规则提供满减优惠，当且仅当 `type` 为 `NORMAL` 且 `scope` 为 `ALL` 或 `CATEGORY` 时必填，其他类型不应填写。 |
| product_coupon.single_usage_info.normal_coupon.threshold | integer | true | 【门槛金额】 使用门槛金额，单位为分，达到该门槛后可享受满减优惠。门槛可以为0，即无门槛。例如：<br><ul><li>满 100 元可用填 `10000`</li><li>满 0.01 元可用填 `1`</li></ul> |
| product_coupon.single_usage_info.normal_coupon.discount_amount | integer | true | 【固定减免金额】 固定减免金额，单位为分，必须大于0。 |
| product_coupon.single_usage_info.discount_coupon | object | false | 【折扣券使用规则】 本商品券内所有批次均以此规则提供折扣优惠，当且仅当 `type` 为 `DISCOUNT` 且 `scope` 为 `ALL` 或 `CATEGORY` 时必填，其他类型不应填写。 |
| product_coupon.single_usage_info.discount_coupon.threshold | integer | true | 【门槛金额】 使用门槛金额，单位为分，达到该门槛后可享受折扣优惠。门槛可以为0，即无门槛。例如：<br><ul><li>满 100 元可用填 `10000`</li><li>满 0.01 元可用填 `1`</li></ul> |
| product_coupon.single_usage_info.discount_coupon.percent_off | integer | true | 【固定减免百分比】 表示减免金额为总金额的百分比，必须大于0。例如：填入 `30` 表示减免 30%，即打 7 折 |
| product_coupon.progressive_bundle_usage_info | object | false | 【多次优惠模式信息】 多次优惠模式配置信息，当且仅当 `usage_mode` 为 `PROGRESSIVE_BUNDLE` 时提供，其他模式不提供。 |
| product_coupon.progressive_bundle_usage_info.count | integer | true | 【可使用次数】 多次优惠领取后用户可使用次数，最少3次，最多15次 |
| product_coupon.progressive_bundle_usage_info.interval_days | integer | false | 【多次优惠使用间隔天数】 多次优惠多次使用之间需要间隔的天数，最高7天。例如：<br><ul><li>间隔 `0` 天表示不限制，使用后当天仍然可以继续使用下一次优惠</li><li>间隔 `1` 天表示使用后当天不再可用，下一次优惠需要等到次日 00:00:00 才能使用</li><li>间隔 `2` 天表示使用后当天和次日不再可用，下一次优惠需要等到第三天 00:00:00 才能使用</li><li>依此类推……</li></ul><br>默认情况下为 `0` 天，即不限制，使用后当天仍然可以继续使用下一次优惠 |
| product_coupon.display_info | object | true | 【展示信息】 商品券展示信息 |
| product_coupon.display_info.name | string(15) | true | 【商品券名称】 商品券名称，长度为3-15个UTF-8字符 |
| product_coupon.display_info.image_url | string | true | 【商品券图片】 商品图片的链接地址，仅支持通过【 [图片上传API](https://pay.weixin.qq.com/doc/brand/4015736285.md)】获取的图片URL地址。<br><ul><li>请参考 [商品券图片设计规范](https://docs.qq.com/doc/DQ2VkYmVUYWpIY2VQ) 进行设计</li><li>要求图片宽高比1:1，建议尺寸1080\*1080</li><li>大小不超过2M</li><li>建议图片格式：透明PNG格式</li><li>需要注意保留透明边距（上下左右各120px）</li></ul> |
| product_coupon.display_info.background_url | string | true | 【商品券背景图】 商品背景图片的URL地址，仅支持通过【 [图片上传API](https://pay.weixin.qq.com/doc/brand/4015736285.md)】获取的图片URL地址。<br><ul><li>要求图片宽高比65:77，建议尺寸1170\*1326</li><li>大小不超过2M</li><li>建议图片格式：JPG/PNG格式</li><li>需要注意保留「商品名称」与「商品图」的安全区域</li></ul> |
| product_coupon.display_info.detail_image_url_list | array[string] | false | 【商品券详情图列表】 商品详情图URL地址列表，用于最多可上传8张图片，仅支持通过【 [图片上传API](https://pay.weixin.qq.com/doc/brand/4015736285.md)】获取的图片URL地址。<br><ul><li>要求图片宽高比65:77，建议尺寸1170\*1326</li><li>大小不超过2M</li><li>建议图片格式：JPG/PNG格式</li></ul> |
| product_coupon.display_info.original_price | integer | false | 【商品原价】 单位为分，用于对外展示，默认为 0，最大为 10000000。不填写时默认为 0 |
| product_coupon.display_info.combo_package_list | array[object] | false | 【适用商品组合】 当 `scope` 为 `SINGLE` 必填，用于对外展示，其他优惠范围选填。最多配置 50 个组合 |
| product_coupon.display_info.combo_package_list.name | string(15) | true | 【适用商品名】 长度不超过15个UTF-8字符 |
| product_coupon.display_info.combo_package_list.pick_count | integer | true | 【可选单品数量】 用户可以从 `choice_list` 中选择的选项数量，例如 10 选 3，则这里填 3 |
| product_coupon.display_info.combo_package_list.choice_list | array[object] | true | 【单品列表】 套餐内包含的选项列表，记录每个单品的信息，最多99个单品，且不能少于设置的 `pick_count` 数量 |
| product_coupon.display_info.combo_package_list.choice_list.name | string(15) | true | 【单品名称】 长度不超过15个UTF-8字符 |
| product_coupon.display_info.combo_package_list.choice_list.price | integer | true | 【单品价格】 单位为分，必须大于0。 |
| product_coupon.display_info.combo_package_list.choice_list.count | integer | true | 【单品数量】 最多99个 |
| product_coupon.display_info.combo_package_list.choice_list.image_url | string | false | 【单品图片】 单品图片URL地址，仅支持通过【 [图片上传API](https://pay.weixin.qq.com/doc/brand/4015736285.md)】获取的图片URL地址，接入领券组件和核销组件的品牌方建议填写。<br><ul><li>要求图片宽高比1:1，建议尺寸1080\*1080</li><li>大小不超过2M</li><li>建议图片格式：透明PNG格式</li><li>需要注意保留透明边距（上下左右各120px）</li></ul> |
| product_coupon.display_info.combo_package_list.choice_list.mini_program_appid | string | false | 【单品跳转小程序AppID】 品牌方可展示单品的小程序AppID，小程序需与品牌方存在绑定关系，接入领券组件和核销组件的品牌方建议填写。需和 `mini_program_path` 一同填写。 |
| product_coupon.display_info.combo_package_list.choice_list.mini_program_path | string | false | 【单品跳转小程序路径】 单品展示信息在小程序内的跳转路径，接入领券组件和核销组件的品牌方建议填写。需和 `mini_program_appid` 一同填写。 |
| product_coupon.out_product_no | string | false | 【外部商品ID】 商户创建商品券时主动传入的外部商品ID，原样返回 |
| product_coupon.state | string | true | 【商品券状态】 商品券状态<br>可选取值<br><ul><li>`AUDITING`:  审批中，审批完成前商品券不可用</li><li>`EFFECTIVE`:  生效中，商品券已生效，可以正常使用</li><li>`DEACTIVATED`:  已失效，品牌方主动调用失效接口使商品券失效</li></ul> |
| product_coupon.deactivate_request_no | string(128) | false | 【失效请求单号】 当且仅当 `state` 为 `DEACTIVATED` 时提供，返回品牌方调用【 [失效商品券API](https://pay.weixin.qq.com/doc/brand/4015736315.md)】时传入的请求流水号 |
| product_coupon.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秒。 |
| product_coupon.deactivate_reason | string(150) | false | 【失效原因】 当且仅当 `state` 为 `DEACTIVATED` 时提供，返回品牌方调用【 [失效商品券API](https://pay.weixin.qq.com/doc/brand/4015736315.md)】时传入的失效原因 |
| stock | object | true | 【批次信息】 该用户商品券发券时使用的批次详情 |
| stock.product_coupon_id | string(40) | true | 【商品券ID】 商品券的唯一标识，由微信支付生成 |
| stock.stock_id | string(40) | true | 【批次ID】 商品券批次的唯一标识，由微信支付生成 |
| stock.remark | string(20) | false | 【备注】 仅配置品牌可见，用于自定义信息 |
| 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/brand/4015736400.md)】或【 [预上传券Code API(多次优惠)](https://pay.weixin.qq.com/doc/brand/4016427797.md)】上传自定义Code，微信支付系统发券时从中随机选取，当预存Code不足时可能影响发券，品牌应及时补充</li><li>`API_ASSIGN`:  品牌方自行指定，品牌方通过【 [向用户发放商品券API](https://pay.weixin.qq.com/doc/brand/4015736390.md)】自行发券时指定，微信支付系统不再进行自动分配。特别注意：这种模式的商品批次只可由品牌方自行发券，无法在摇一摇有优惠等微信支付渠道投放；商品券的 `usage_mode` 为 `PROGRESSIVE_BUNDLE` 时不可使用本模式</li></ul> |
| stock.coupon_code_count_info | object | false | 【品牌方预上传的券Code数量信息】 当且仅当 `coupon_code_mode` 为 `UPLOAD` 时存在此字段 |
| stock.coupon_code_count_info.total_count | integer | true | 【已上传的Code总数】 品牌方为此批次已经上传过的券Code总数量 |
| stock.coupon_code_count_info.available_count | integer | true | 【当前可用的Code数】 品牌方为此批次已经上传过的券Code中，当前剩余可用的券Code数量 |
| 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 秒内可用，不与自然日对齐。取值范围为 3600~86400，且仅支持 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.progressive_bundle_usage_rule | object | false | 【多次优惠使用规则】 当且仅当 `usage_mode` 为 `PROGRESSIVE_BUNDLE` 时提供，其他场景不提供 |
| stock.progressive_bundle_usage_rule.coupon_available_period | object | true | 【券可核销时间】 确定用户领券后在什么时间段内可以核销 |
| stock.progressive_bundle_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.progressive_bundle_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.progressive_bundle_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.progressive_bundle_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.progressive_bundle_usage_rule.coupon_available_period.weekly_available_period | object | false | 【每周固定可用时间】 日期区间内，每周固定时间可以使用。可与 `available_days` 和 `wait_days_after_receive` 一同配置，一同配置时条件需同时满足券才可用（时间范围取交集）。<br>注：不可与 `irregular_available_period_list` 同时配置 |
| stock.progressive_bundle_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.progressive_bundle_usage_rule.coupon_available_period.weekly_available_period.day_period_list | array[object] | false | 【当天可用时间段】 生效当天特定时间段内有效，可以配置多个时间段。最多可以配置 3 个时间段。不配置则全天可用。 |
| stock.progressive_bundle_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.progressive_bundle_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.progressive_bundle_usage_rule.coupon_available_period.irregular_available_period_list | array[object] | false | 【指定可用时间段】 可以配置多个无规律时间段，不同区间内请勿重叠，最多可配置2个区间。<br>注：不可与 `available_days`、 `wait_days_after_receive`、 `weekly_available_period` 同时配置 |
| stock.progressive_bundle_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.progressive_bundle_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.progressive_bundle_usage_rule.coupon_available_period.available_seconds | integer | false | 【领取后N秒内有效】 日期区间内，用户领券后立即生效，自领取时刻起 N 秒内可用，不与自然日对齐。取值范围为 3600~86400，且仅支持 3600 的整数倍。<br>注：不可与 `available_days`、 `wait_days_after_receive`、 `weekly_available_period`、 `irregular_available_period_list` 同时配置 |
| stock.progressive_bundle_usage_rule.normal_coupon | object | false | 【满减券使用规则】 当且仅当 `type` 为 `NORMAL` 时必填，其他类型不应填写 |
| stock.progressive_bundle_usage_rule.normal_coupon.threshold | integer | true | 【门槛金额】 使用门槛金额，单位为分，达到该门槛后可享受满减优惠。门槛可以为0，即无门槛。例如：<br><ul><li>满 100 元可用填 `10000`</li><li>满 0.01 元可用填 `1`</li></ul> |
| stock.progressive_bundle_usage_rule.normal_coupon.discount_amount | integer | true | 【固定减免金额】 固定减免金额，单位为分，必须大于0。 |
| stock.progressive_bundle_usage_rule.discount_coupon | object | false | 【折扣券使用规则】 当且仅当 `type` 为 `DISCOUNT` 时必填，其他类型不应填写\` |
| stock.progressive_bundle_usage_rule.discount_coupon.threshold | integer | true | 【门槛金额】 使用门槛金额，单位为分，达到该门槛后可享受折扣优惠。门槛可以为0，即无门槛。例如：<br><ul><li>满 100 元可用填 `10000`</li><li>满 0.01 元可用填 `1`</li></ul> |
| stock.progressive_bundle_usage_rule.discount_coupon.percent_off | integer | true | 【固定减免百分比】 表示减免金额为总金额的百分比，必须大于0。例如：填入 `30` 表示减免 30%，即打 7 折 |
| stock.progressive_bundle_usage_rule.exchange_coupon | object | false | 【兑换券使用规则】 当且仅当 `type` 为 `EXCHANGE` 时必填，其他类型不应填写 |
| stock.progressive_bundle_usage_rule.exchange_coupon.threshold | integer | true | 【门槛金额】 使用门槛金额，单位为分，达到该门槛后可进行兑换。门槛可以为0，即无门槛兑换。例如：<br><ul><li>满 100 元可用填 `10000`</li><li>满 0.01 元可用填 `1`</li></ul> |
| stock.progressive_bundle_usage_rule.exchange_coupon.exchange_price | integer | true | 【固定兑换价格】 单位为分，必须大于或等于0。 |
| stock.stock_bundle_info | object | false | 【批次组信息】 批次所在批次组信息，当且仅当 `usage_mode` 为 `PROGRESSIVE_BUNDLE` 时提供 |
| stock.stock_bundle_info.stock_bundle_id | string(40) | true | 【批次所属批次组ID】 商品券批次组的唯一标识，【 [创建商品券(多次优惠)](https://pay.weixin.qq.com/doc/brand/4016427368.md)】或【 [添加商品券批次组](https://pay.weixin.qq.com/doc/brand/4016279732.md)】时由微信支付生成 |
| stock.stock_bundle_info.stock_bundle_index | 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/brand/4015736285.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> |
| stock.sent_count_info | object | true | 【已发放次数】 本批次已发放次数 |
| stock.sent_count_info.total_count | integer | true | 【已发放总次数】 批次在生命周期内已发放次数 |
| stock.sent_count_info.today_count | integer | true | 【当天已发放次数】 批次在当天已发放次数 |
| stock.state | string | true | 【批次状态】 商品券批次状态<br>可选取值<br><ul><li>`AUDITING`:  审批中</li><li>`SENDING`:  发放中</li><li>`PAUSED`:  已暂停</li><li>`STOPPED`:  已停止，当前已到达结束时间</li><li>`DEACTIVATED`:  已失效，品牌方主动调用失效接口使批次失效</li></ul> |
| stock.deactivate_request_no | string(128) | false | 【失效请求单号】 当且仅当 `state` 为 `DEACTIVATED` 时提供，返回品牌方调用失效接口时传入的请求流水号 |
| stock.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秒。 |
| stock.deactivate_reason | string(150) | false | 【失效原因】 当且仅当 `state` 为 `DEACTIVATED` 时提供，返回品牌方调用【 [失效商品券批次API](https://pay.weixin.qq.com/doc/brand/4015736352.md)】时传入的失效原因 |
| attach | string | false | 【自定义附加信息】 调用发券接口时品牌方使用 `attach` 字段主动设置的附加信息。微信支付不会解析该信息，仅在查询用户商品券和回调中原样返回。<br>注： 发券渠道多样，只有品牌方通过发券接口发放的券才会在查询和回调中携带此字段，其他渠道发放的券 `attach` 为空。 |
| channel_custom_info | string(1000) | false | 【渠道自定义信息】 使用微信支付提供的其他渠道（比如「摇一摇有优惠」）发放商品券时，渠道可能会设置该渠道特定的自定义信息，请根据 `send_channel` 字段判断如何解析本字段。不同渠道的自定义信息格式不同，请根据对应渠道的文档解析。 |
| coupon_tag_info | object | false | 【用户商品券标签信息】 用户商品券标签信息 |
| coupon_tag_info.coupon_tag_list | array[string] | false | 【用户商品券标签列表】 用户商品券标签列表<br>可选取值<br><ul><li>`MEMBER`:  会员标签，标识该用户商品券为会员券</li></ul> |
| coupon_tag_info.member_tag_info | object | false | 【会员标签信息】 当用户商品券标签列表中有 `MEMBER` 时，该字段必填 |
| coupon_tag_info.member_tag_info.member_card_id | string | true | 【会员卡模板ID】 通过 [商家名片会员API](https://pay.weixin.qq.com/doc/brand/4015582711.md) 创建会员卡模板成功后，获得的会员卡模板ID |
## 错误码

以下是本接口返回的错误码列表。详细错误码规则，请参考[微信支付接口规则-错误码和错误提示](https://pay.weixin.qq.com/doc/brand/4015407525.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/brand/4015407525.md) |
| 401 | SIGN\_ERROR | 验证不通过 | 请参阅 [签名常见问题](https://pay.weixin.qq.com/doc/brand/4015597625.md) |
| 500 | SYSTEM\_ERROR | 系统异常，请稍后重试 | 请稍后重试 |
| 400 | INVALID\_REQUEST | 单券使用模式的商品券批次，应该在「单券使用规则」中包含对应类型的优惠规则。对于文档中标记不应填写的优惠规则应删除。 | 请在「单券使用规则」中包含对应类型的优惠规则，并删除文档中标记不应填写的优惠规则。 |
| 400 | INVALID\_REQUEST | 多次优惠使用模式的商品券批次，应该在「多次优惠使用规则」中包含对应类型的优惠规则，且数量与多次优惠的优惠次数相等 | 在「多次优惠使用规则」中包含对应类型的优惠规则，且数量与多次优惠的优惠次数相等 |
| 400 | INVALID\_REQUEST | 单品满减券或单品折扣券不应在商品券中设置「满减券使用规则」或「折扣券使用规则」，而是应该在商品券批次中设置 | 请删除商品券中的「满减券使用规则」或「折扣券使用规则」，并在商品券批次中设置对应的优惠规则 |
| 403 | NO\_AUTH | 品牌没有此接口权限 | 品牌没有此接口权限 |
| 404 | NOT\_FOUND | 用户券不存在 | 用户券不存在 |
| 400 | INVALID\_REQUEST | 商品券支持APP核销时，必须提供「APP跳转路径」 | 请提供「APP跳转路径」参数 |
| 400 | PARAM\_ERROR | 分页大小超出限制，请根据接口文档调整到允许的范围 | 请调整分页大小到规定范围 |
| 400 | INVALID\_REQUEST | 商品券支持小程序核销时，必须提供「小程序AppID」 | 请提供「小程序AppID」 |
| 400 | INVALID\_REQUEST | 单品券必须提供商品原价，请补充 | 请补充商品原价 |
| 400 | INVALID\_REQUEST | 商品券支持小程序核销时，必须提供「小程序跳转路径」 | 请提供提供「小程序跳转路径」 |
| 400 | PARAM\_ERROR | 时间字符串格式错误，请使用 RFC3339 标准格式 | 请使用 RFC3339 标准格式 |
| 400 | INVALID\_REQUEST | 单券模式下，全场满减券应在商品券中提供满减券使用规则信息 | 请在商品券中提供「满减券使用规则信息」 |
| 400 | INVALID\_REQUEST | 每周固定可用时间(weekly\_available\_period)中提供当天可用时间段时(day\_period\_list)，每周可用星期数(day\_list)必填 | 请补充 每周可用星期数(day\_list) |
| 400 | INVALID\_REQUEST | 单券模式下，全场券需要提供「单券模式信息(single\_usage\_info)」 | 请提供单券模式信息(single\_usage\_info) |
| 400 | INVALID\_REQUEST | 多次优惠模式下必须提供「多次优惠模式信息(sequential\_usage\_info)」 | 请填写 多次优惠模式信息(sequential\_usage\_info) |
| 400 | INVALID\_REQUEST | 传入的OpenID不合法 | 请使用参数 AppID 对应的的OpenID |
| 400 | INVALID\_REQUEST | 用户券状态非法 | 用户券状态非法 |

请求示例

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


应答示例

> 200 OK

退回已经核销的用户券

```
{
  "coupon_code" : "Code_123456",
  "coupon_state" : "EFFECTIVE",
  "valid_begin_time" : "2025-08-02T00:00:00+08:00",
  "valid_end_time" : "2025-08-31T23:59:59+08:00",
  "receive_time" : "2025-08-02T00:00:00+08:00",
  "send_request_no" : "MCHSEND202003101234",
  "send_channel" : "API",
  "confirm_request_no" : "MCHCONFIRM202003101234",
  "confirm_time" : "2025-08-02T00:00:05+08:00",
  "single_usage_detail" : {
    "use_request_no" : "MCHUSE202003101234",
    "use_time" : "2025-08-03T12:00:00+08:00",
    "associated_order_info" : {
      "transaction_id" : "4200000000123456789123456789"
    },
    "return_request_no" : "MCHRETURN202003101234",
    "return_time" : "2025-08-03T12:01:00+08:00"
  },
  "product_coupon" : {
    "product_coupon_id" : "1000000013",
    "scope" : "ALL",
    "type" : "DISCOUNT",
    "usage_mode" : "SINGLE",
    "single_usage_info" : {
      "discount_coupon" : {
        "threshold" : 10000,
        "percent_off" : 20
      }
    },
    "display_info" : {
      "name" : "全场满100立打8折-新名字",
      "image_url" : "https://wxpaylogo.qpic.cn/wxpaylogo/xxxxx/xxx",
      "background_url" : "https://wxpaylogo.qpic.cn/wxpaylogo/xxxxx/xxx",
      "detail_image_url_list" : [
        "https://wxpaylogo.qpic.cn/wxpaylogo/xxxxx/xxx"
      ]
    },
    "state" : "EFFECTIVE",
    "out_product_no" : "Product_1234567890"
  },
  "stock" : {
    "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"
  },
  "attach" : "any attach content"
}

```
