首页文档中心注册品牌
文档中心
首页文档中心注册品牌
快速开始产品文档Skills&开发工具更新日志
产品文档
快速开始产品文档Skills&开发工具更新日志
AI开发助手

失效用户商品券

更新时间：2025.09.02
||| 安装 Skill

品牌方可以通过本接口将用户的商品券失效

前置条件：已经给用户发券成功，且商品券的 usage_mode 不为 PROGRESSIVE_BUNDLE

接口说明

支持商户：【品牌商户】

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

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

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

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

请求参数

Header  HTTP头参数

 Authorization 　必填　string

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

 Accept 　必填　string

请设置为application/json

 Content-Type 　必填　string

请设置为application/json

 Wechatpay-Serial 　必填　string

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

path  路径参数

 coupon_code 　必填   string(40)

【用户商品券Code】 用户商品券的唯一标识

 openid 　必填   string

【用户OpenID】 OpenID信息，用户在AppID下的唯一标识，获取方式参考OpenID

body  包体参数

 product_coupon_id 　必填   string

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

 stock_id 　必填   string

【批次ID】 商品券批次的唯一标识，商品券批次创建时由微信支付生成（可使用【创建商品券API】或【添加商品券批次API】创建），请确保该批次属于 product_coupon_id 对应的商品券

 appid 　必填   string

【公众账号ID】 公众账号ID也称AppID，是（微信开放平台、微信公众平台）为开发者提供的一个唯一标识，用于识别开发者的应用程序(APP、小程序、公众号)。 开发者需要先在微信开放平台或微信公众平台中申请ID，然后在品牌经营平台中绑定，详见品牌经营平台指引。

 out_request_no 　必填   string(40)

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

 deactivate_reason 　必填   string(150)

【失效原因】 记录用户商品券的失效原因，长度不超过150个UTF-8字符

请求示例

curl
Java
Go

POST

使用户券失效

1curl -X POST \
2  https://api.mch.weixin.qq.com/brand/marketing/product-coupon/users/oh-394z-6CGkNoJrsDLTTUKiAnp4/coupons/Code_123456/deactivate \
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    "product_coupon_id" : "1000000013",
9    "appid" : "wx233544546545989",
10    "deactivate_reason" : "商品已下线，使用户商品券失效",
11    "stock_id" : "1000000013001",
12    "out_request_no" : "MCHDEACTIVATE202003101234"
13  }'
14

应答参数
折叠全部参数

200 OK

 coupon_code 　必填   string(40)

【用户商品券Code】 用户商品券的唯一标识

 coupon_state 　必填   string

【用户商品券状态】 

可选取值

 valid_begin_time 　必填   string

【有效期开始时间】 用户商品券可用开始时间，遵循rfc3339标准格式，格式为yyyy-MM-DDTHH:mm:ss+TIMEZONE，yyyy-MM-DD表示年月日，T出现在字符串中，表示time元素的开头，HH:mm:ss表示时分秒，TIMEZONE表示时区（+08:00表示东八区时间，领先UTC 8小时，即北京时间）

 valid_end_time 　必填   string

【有效期结束时间】 用户商品券可用结束时间。遵循rfc3339标准格式，格式为yyyy-MM-DDTHH:mm:ss+TIMEZONE，yyyy-MM-DD表示年月日，T出现在字符串中，表示time元素的开头，HH:mm:ss表示时分秒，TIMEZONE表示时区（+08:00表示东八区时间，领先UTC 8小时，即北京时间）

 receive_time 　必填   string

【领券时间】 用户领券时间。遵循rfc3339标准格式，格式为yyyy-MM-DDTHH:mm:ss+TIMEZONE，yyyy-MM-DD表示年月日，T出现在字符串中，表示time元素的开头，HH:mm:ss表示时分秒，TIMEZONE表示时区（+08:00表示东八区时间，领先UTC 8小时，即北京时间）

 send_request_no 　必填   string(128)

【发券请求单号】 发券时传入的请求流水号

 send_channel 　必填   string

【发券渠道】 描述用户商品券是经由什么渠道发送的

可选取值

  • BRAND_MANAGE:  摇一摇有优惠，通过摇一摇有优惠渠道发放

  • API:  品牌方自主发券，品牌方通过发券接口自主发券到商家名片

  • RECEIVE_COMPONENT:  小程序领券组件，品牌方通过小程序领券组件发券

  • MEMBER:  会员，品牌方通过会员相关活动或渠道进行发券

  • STICKER_GIFT:  贴图有礼，用户参与品牌贴图有礼活动后发放

 confirm_request_no 　选填   string

【确认请求单号】 品牌方确认发券请求时传入的的请求流水号。当且仅当 品牌方调用【确认发放用户商品券API】后提供。

 confirm_time 　选填   string

【确认发放时间】 品牌方确认发券时间，当且仅当 品牌方调用【确认发放用户商品券API】后提供。遵循rfc3339标准格式，格式为yyyy-MM-DDTHH:mm:ss+TIMEZONE，yyyy-MM-DD表示年月日，T出现在字符串中，表示time元素的开头，HH:mm:ss表示时分秒，TIMEZONE表示时区（+08:00表示东八区时间，领先UTC 8小时，即北京时间）

 deactivate_request_no 　选填   string(128)

【失效请求单号】 品牌方失效券请求时传入的的请求流水号。当且仅当 coupon_state 为 DEACTIVATED 时提供，返回品牌方调用【失效用户商品券API】或【失效用户商品券组API】时传入的请求流水号

 deactivate_time 　选填   string

【失效时间】 失效时间，当且仅当 coupon_state 为 DEACTIVATED 时提供。遵循rfc3339标准格式，格式为yyyy-MM-DDTHH:mm:ss+TIMEZONE，yyyy-MM-DD表示年月日，T出现在字符串中，表示time元素的开头，HH:mm:ss表示时分秒，TIMEZONE表示时区（+08:00表示东八区时间，领先UTC 8小时，即北京时间）

 deactivate_reason 　选填   string(150)

【失效原因】 失效券的原因，当且仅当 coupon_state 为 DEACTIVATED 时提供，返回品牌方调用【失效用户商品券API】或【失效用户商品券组API】时传入的失效原因

 single_usage_detail 　选填   object

【单券使用详情】 当且仅当 usage_mode 为 SINGLE 时提供

属性

 use_request_no 　选填   string

【券核销请求单号】 券核销的请求流水号，当且仅当用户商品券状态 coupon_state 为 USED 时提供

 use_time 　选填   string

【券核销时间】 券被核销的时间，当且仅当用户商品券状态 coupon_state 为 USED 时提供。遵循rfc3339标准格式，格式为yyyy-MM-DDTHH:mm:ss+TIMEZONE，yyyy-MM-DD表示年月日，T出现在字符串中，表示time元素的开头，HH:mm:ss表示时分秒，TIMEZONE表示时区（+08:00表示东八区时间，领先UTC 8小时，即北京时间）

 return_request_no 　选填   string

【退券请求单号】 品牌退券时传入的请求流水号，当且仅当券发生了退回后提供此字段

 return_time 　选填   string

【退券时间】 券被退回的时间，当且仅当券发生了退回后提供此字段。遵循rfc3339标准格式，格式为yyyy-MM-DDTHH:mm:ss+TIMEZONE，yyyy-MM-DD表示年月日，T出现在字符串中，表示time元素的开头，HH:mm:ss表示时分秒，TIMEZONE表示时区（+08:00表示东八区时间，领先UTC 8小时，即北京时间）

 associated_order_info 　选填   object

【券核销的微信支付订单信息】 券核销对应的微信支付订单信息，当且仅当用户商品券状态 coupon_state 为 USED 时提供,
注:
1、associated_order_info与 associated_pay_score_order_info 会根据核销请求时的传入参数决定返回对应字段
2、订单信息必须至少传入 transaction_id 与 out_trade_no 之一，亦可同时传入，同时传入时应保证二者指向同一笔微信支付单。

属性

 transaction_id 　选填   string

【微信支付单号】 由微信支付生成的支付单唯一标识，可以唯一定位到一笔微信支付单。

注：订单信息必须至少传入 transaction_id 与 out_trade_no 之一，亦可同时传入，同时传入时应保证二者指向同一笔微信支付单。

 out_trade_no 　选填   string

【商户订单号】 在微信支付支付时传入的商户订单号，在商户侧具有唯一性，因此提供此字段时应同时提供下单商户号：

  • 如果此单为服务商模式下单，则需提供 父商户号 mchid 以及 子商户号 sub_mchid

  • 如果此单为直连商户模式下单，则需提供 直连商户号 mchid

注：订单信息必须至少传入 transaction_id 与 out_trade_no 之一，亦可同时传入，同时传入时应保证二者指向同一笔微信支付单。

 mchid 　选填   string

【商户号】 当提供 out_trade_no 时此字段必传，否则可以省略。参考如下规则传入：

  • 若为服务商模式，则此字段为服务商商户号

  • 若为直连商户模式，则此字段为商户号

 sub_mchid 　选填   string

【子商户号】 当提供 out_trade_no 时，参考如下规则传入：

  • 若为服务商模式，则此字段必填，为子商户号

  • 若为直连商户模式，则此字段为空

不提供 out_trade_no 时可忽略此字段

 associated_pay_score_order_info 　选填   object

【券核销的关联微信支付分订单信息】 券核销的关联微信支付分订单信息，当且仅当用户商品券状态 coupon_state 为 USED 时提供,
注:
1、associated_order_info与 associated_pay_score_order_info 会根据核销请求时的传入参数决定返回对应字段

2、订单信息必须至少传入 order_id 与 out_order_no 之一，亦可同时传入，同时传入时应保证二者指向同一笔微信支付单。

属性

 order_id 　选填   string

【微信支付服务订单号】 支付分订单在微信侧的唯一标识。

注：订单信息必须至少传入 order_id 与 out_order_no 之一，亦可同时传入，同时传入时应保证二者指向同一笔微信支付单。

 out_order_no 　选填   string

【商户服务订单号】 商户系统内部服务订单号，要求32个字符内，只能是数字、大小写字母_-| 且在同一个商户号下唯一。：

  • 如果此单为服务商模式下单，则需提供 父商户号 mchid 以及 子商户号 sub_mchid

  • 如果此单为直连商户模式下单，则需提供 直连商户号 mchid

注：订单信息必须至少传入 order_id 与 out_order_no 之一，亦可同时传入，同时传入时应保证二者指向同一笔微信支付服务单。

 mchid 　选填   string

【商户号】 当提供 out_order_no 时此字段必传，否则可以省略。参考如下规则传入：

  • 若为服务商模式，则此字段为服务商商户号

  • 若为直连商户模式，则此字段为商户号

 sub_mchid 　选填   string

【子商户号】 当提供 out_order_no 时，参考如下规则传入：

  • 若为服务商模式，则此字段必填，为子商户号

  • 若为直连商户模式，则此字段为空

不提供 out_order_no 时可忽略此字段

 saved_amount 　选填   integer

【优惠金额】 使用本券的实际优惠金额，单位为分
注：

  • 当本券为全场/品类折扣券（scope=ALL 或 CATEGORY）时，提供的是商户传入的值

 use_product_no_list 　选填   array[string]

【核销商品编码列表】 核销商品编码列表
注：

  • 当该券优惠范围为单品或品类且商户核销时传入的商品编码列表正确时提供

 product_coupon 　必填   object

【商品券信息】 该用户商品券对应的商品券详情

属性

 product_coupon_id 　必填   string(40)

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

 scope 　必填   string

【优惠范围】 商品券优惠范围

可选取值

  • ALL:  全场商品可用券，此时券类型 type 仅可配置为 NORMAL 或 DISCOUNT

  • SINGLE:  部分商品可用券，此时券类型 type 配置不受限制，即可配置为 NORMAL、DISCOUNT 或 EXCHANGE

  • CATEGORY:  品类券。适用于商户对某一品类商品提供优惠的场景；系统侧不维护商品/品类清单，具体可用商品范围由商户在 display_info 描述、图片等字段中向用户告知，并在核销时由商户自行判定。此时券类型 type 仅可配置为 NORMAL 或 DISCOUNT

 type 　必填   string

【商品券类型】 商品券的优惠类型

可选取值

  • NORMAL:  满减券

  • DISCOUNT:  折扣券

  • EXCHANGE:  兑换券，仅在 scope 为 SINGLE 时可配置

 usage_mode 　必填   string

【使用模式】 商品券使用模式

可选取值

  • SINGLE:  单券，即用户只能使用一次，使用后券失效

  • PROGRESSIVE_BUNDLE:  多次优惠，由一组批次组成，每阶梯次序对应一个批次。用户按顺序使用，每次核销后发放下一张券，直到用完为止

 single_usage_info 　选填   object

【单券模式信息】 单券模式配置信息，仅当 usage_mode 为 SINGLE 时提供，其他场景不提供。

属性

 normal_coupon 　选填   object

【满减券使用规则】 本商品券内所有批次均以此规则提供满减优惠，当且仅当 type 为 NORMAL 且 scope 为 ALL 或 CATEGORY 时必填，其他类型不应填写。

属性

 threshold 　必填   integer

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

  • 满 100 元可用填 10000

  • 满 0.01 元可用填 1

 discount_amount 　必填   integer

【固定减免金额】 固定减免金额，单位为分，必须大于0。

 discount_coupon 　选填   object

【折扣券使用规则】 本商品券内所有批次均以此规则提供折扣优惠，当且仅当 type 为 DISCOUNT 且 scope 为 ALL 或 CATEGORY 时必填，其他类型不应填写。

属性

 threshold 　必填   integer

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

  • 满 100 元可用填 10000

  • 满 0.01 元可用填 1

 percent_off 　必填   integer

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

 progressive_bundle_usage_info 　选填   object

【多次优惠模式信息】 多次优惠模式配置信息，当且仅当 usage_mode 为 PROGRESSIVE_BUNDLE 时提供，其他模式不提供。

属性

 count 　必填   integer

【可使用次数】 多次优惠领取后用户可使用次数，最少3次，最多15次

 interval_days 　选填   integer

【多次优惠使用间隔天数】 多次优惠多次使用之间需要间隔的天数，最高7天。例如：

  • 间隔 0 天表示不限制，使用后当天仍然可以继续使用下一次优惠

  • 间隔 1 天表示使用后当天不再可用，下一次优惠需要等到次日 00:00:00 才能使用

  • 间隔 2 天表示使用后当天和次日不再可用，下一次优惠需要等到第三天 00:00:00 才能使用

  • 依此类推……

默认情况下为 0 天，即不限制，使用后当天仍然可以继续使用下一次优惠

 display_info 　必填   object

【展示信息】 商品券展示信息

属性

 name 　必填   string(25)

【商品券名称】 商品券名称，长度为3-25个UTF-8字符

 image_url 　必填   string

【商品券图片】 商品图片的链接地址，仅支持通过【图片上传API】获取的图片URL地址。

  • 请参考商品券图片设计规范进行设计

  • 要求图片宽高比1:1，建议尺寸1080*1080

  • 大小不超过2M

  • 建议图片格式：透明PNG格式

  • 需要注意保留透明边距（上下左右各120px）

 background_url 　必填   string

【商品券背景图】 商品背景图片的URL地址，仅支持通过【图片上传API】获取的图片URL地址。

  • 要求图片宽高比65:77，建议尺寸1170*1326

  • 大小不超过2M

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

  • 需要注意保留「商品名称」与「商品图」的安全区域

 detail_image_url_list 　选填   array[string]

【商品券详情图列表】 商品详情图URL地址列表，用于最多可上传8张图片，仅支持通过【图片上传API】获取的图片URL地址。

  • 要求图片宽高比65:77，建议尺寸1170*1326

  • 大小不超过2M

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

 original_price 　选填   integer

【商品原价】 单位为分，用于对外展示，默认为 0，最大为 10000000。不填写时默认为 0

 combo_package_list 　选填   array[object]

【适用商品组合】 当 scope 为 SINGLE 必填，用于对外展示，其他优惠范围选填。最多配置 50 个组合

属性

 name 　必填   string(15)

【适用商品名】 长度不超过15个UTF-8字符

 pick_count 　必填   integer

【可选单品数量】 用户可以从 choice_list 中选择的选项数量，例如 10 选 3，则这里填 3

 choice_list 　必填   array[object]

【单品列表】 套餐内包含的选项列表，记录每个单品的信息，最多99个单品，且不能少于设置的pick_count数量

属性

 name 　必填   string(15)

【单品名称】 长度不超过15个UTF-8字符

 price 　必填   integer

【单品价格】 单位为分，必须大于0。

 count 　必填   integer

【单品数量】 最多99个

 image_url 　选填   string

【单品图片】 单品图片URL地址，仅支持通过【图片上传API】获取的图片URL地址，接入领券组件和核销组件的品牌方建议填写。

  • 要求图片宽高比1:1，建议尺寸1080*1080

  • 大小不超过2M

  • 建议图片格式：透明PNG格式

  • 需要注意保留透明边距（上下左右各120px）

 mini_program_appid 　选填   string

【单品跳转小程序AppID】 品牌方可展示单品的小程序AppID，小程序需与品牌方存在绑定关系，接入领券组件和核销组件的品牌方建议填写。需和 mini_program_path 一同填写。

 mini_program_path 　选填   string

【单品跳转小程序路径】 单品展示信息在小程序内的跳转路径，接入领券组件和核销组件的品牌方建议填写。需和 mini_program_appid 一同填写。

 out_product_no 　选填   string

【外部商品ID】 商户创建商品券时主动传入的外部商品ID，原样返回

 state 　必填   string

【商品券状态】 商品券状态

可选取值

  • AUDITING:  审批中，审批完成前商品券不可用

  • EFFECTIVE:  生效中，商品券已生效，可以正常使用

  • DEACTIVATED:  已失效，品牌方主动调用失效接口使商品券失效

 deactivate_request_no 　选填   string(128)

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

 deactivate_time 　选填   string

【失效时间】 当且仅当 state 为 DEACTIVATED 时提供，遵循rfc3339标准格式，格式为yyyy-MM-DDTHH:mm:ss+TIMEZONE，yyyy-MM-DD表示年月日，T出现在字符串中，表示time元素的开头，HH:mm:ss表示时分秒，TIMEZONE表示时区（+08:00表示东八区时间，领先UTC 8小时，即北京时间）。例如：2015-05-20T13:29:35+08:00表示，北京时间2015年5月20日 13点29分35秒。

 deactivate_reason 　选填   string(150)

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

 show_as_exchange 　选填   boolean

【是否展示兑换价】 是否按兑换价展示商品券。true 表示 C 端以「商品原价 − 满减金额」展示兑换价。仅当开关为 true 时返回本字段；为 false 或未设置时不返回，商户应按未开启（按满减金额展示）处理。

 available_product_no_list 　选填   array[string]

【可用商品编码列表】 商户创建商品券时主动传入的可用商品编码，原样返回

 stock 　必填   object

【批次信息】 该用户商品券发券时使用的批次详情

属性

 product_coupon_id 　必填   string(40)

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

 stock_id 　必填   string(40)

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

 remark 　选填   string(20)

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

 coupon_code_mode 　必填   string

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

可选取值

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

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

  • API_ASSIGN:  品牌方自行指定，品牌方通过【向用户发放商品券API】自行发券时指定，微信支付系统不再进行自动分配。特别注意：这种模式的商品批次只可由品牌方自行发券，无法在摇一摇有优惠等微信支付渠道投放；商品券的 usage_mode 为 PROGRESSIVE_BUNDLE 时不可使用本模式

 coupon_code_count_info 　选填   object

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

属性

 total_count 　必填   integer

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

 available_count 　必填   integer

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

 stock_send_rule 　必填   object

【发放规则】 发放规则

属性

 max_count 　必填   integer

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

 max_count_per_day 　选填   integer

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

 max_count_per_user 　必填   integer

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

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

距离当前创建批次的时间不能超过90天，批次有效期最长不超过366天，摇优惠场景建议设置批次时间大于等于5天

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

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

 available_days 　选填   integer

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

  • 生效当天内有效填 1

  • 生效后2天内有效填 2

  • 依此类推……

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

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

注：不可与 irregular_available_period_list 同时配置

 wait_days_after_receive 　选填   integer

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

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

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

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

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

注：不可与 irregular_available_period_list 同时配置

 weekly_available_period 　选填   object

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

注：不可与 irregular_available_period_list 同时配置

属性

 day_list 　必填   array[string]

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

可选取值

  • MONDAY:  周一可用

  • TUESDAY:  周二可用

  • WEDNESDAY:  周三可用

  • THURSDAY:  周四可用

  • FRIDAY:  周五可用

  • SATURDAY:  周六可用

  • SUNDAY:  周日可用

 day_period_list 　选填   array[object]

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

属性

 begin_time 　必填   integer

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

 end_time 　必填   integer

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

 irregular_available_period_list 　选填   array[object]

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

注：不可与 available_days、wait_days_after_receive、weekly_available_period 同时配置

属性

 begin_time 　必填   string

【开始时间】 区间开始时间，遵循rfc3339标准格式，格式为yyyy-MM-DDTHH:mm:ss+TIMEZONE，yyyy-MM-DD表示年月日，T出现在字符串中，表示time元素的开头，HH:mm:ss表示时分秒，TIMEZONE表示时区（+08:00表示东八区时间，领先UTC 8小时，即北京时间）。例如：2015-05-20T13:29:35+08:00表示，北京时间2015年5月20日 13点29分35秒。

 end_time 　必填   string

【结束时间】 区间结束时间，遵循rfc3339标准格式，格式为yyyy-MM-DDTHH:mm:ss+TIMEZONE，yyyy-MM-DD表示年月日，T出现在字符串中，表示time元素的开头，HH:mm:ss表示时分秒，TIMEZONE表示时区（+08:00表示东八区时间，领先UTC 8小时，即北京时间）。例如：2015-05-20T13:29:35+08:00表示，北京时间2015年5月20日 13点29分35秒。

 available_seconds 　选填   integer

【领取后N秒内有效】 日期区间内，用户领券后立即生效，自领取时刻起 N 秒内可用，不与自然日对齐。取值范围为 3600~86400，且仅支持 3600 的整数倍。

注：不可与 available_days、wait_days_after_receive、weekly_available_period、irregular_available_period_list 同时配置

 normal_coupon 　选填   object

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

属性

 threshold 　必填   integer

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

  • 满 100 元可用填 10000

  • 满 0.01 元可用填 1

 discount_amount 　必填   integer

【固定减免金额】 固定减免金额，单位为分，必须大于0。

 discount_coupon 　选填   object

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

属性

 threshold 　必填   integer

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

  • 满 100 元可用填 10000

  • 满 0.01 元可用填 1

 percent_off 　必填   integer

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

 exchange_coupon 　选填   object

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

属性

 threshold 　必填   integer

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

  • 满 100 元可用填 10000

  • 满 0.01 元可用填 1

 exchange_price 　必填   integer

【固定兑换价格】 单位为分，必须大于或等于0。

 usage_rule_display_info 　必填   object

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

属性

 coupon_usage_method_list 　必填   array[string]

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

可选取值

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

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

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

  • PAYMENT_CODE:  微信支付付款码核销，用户点击券“立即使用”将跳转至微信支付钱包付款码，品牌方扫描付款码后可通过付款码获取到用户openid，通过openid查询并核销用户券，核销后再发起下单，适合线下支付场景

 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的H5跳转路径】 品牌方APP的H5跳转路径。在 app_jump_type 为 H5 时必填。

 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 一同填写。

 app_jump_type 　选填   string

【APP跳转类型】 APP跳转类型，在 coupon_usage_method_list 中包含 APP 时必填。

可选取值

  • H5:  跳转H5，点击券立即使用跳转至配置的H5页面

  • PASSCODE_LINK:  口令链接，点击券立即使用展示口令链接供用户复制使用

  • USAGE_GUIDE:  展示使用指引，引导前往APP核销

 passcode_link 　选填   string

【口令链接】 口令链接。在 app_jump_type 为 PASSCODE_LINK 时必填。

 coupon_display_info 　必填   object

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

属性

 code_display_mode 　必填   string

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

可选取值

  • INVISIBLE:  不展示Code

  • BARCODE:  条形码

  • QRCODE:  二维码

 background_color 　选填   string

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

 entrance_mini_program 　选填   object

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

属性

 appid 　必填   string

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

 path 　必填   string

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

 entrance_wording 　必填   string(5)

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

 guidance_wording 　必填   string(6)

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

 entrance_official_account 　选填   object

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

属性

 appid 　必填   string

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

 notify_config 　必填   object

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

属性

 notify_appid 　必填   string

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

 store_scope 　必填   string

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

可选取值

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

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

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

 sent_count_info 　必填   object

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

属性

 total_count 　必填   integer

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

 today_count 　必填   integer

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

 state 　必填   string

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

可选取值

  • AUDITING:  审批中

  • SENDING:  发放中

  • PAUSED:  已暂停

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

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

 deactivate_request_no 　选填   string(128)

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

 deactivate_time 　选填   string

【失效时间】 当且仅当 state 为 DEACTIVATED 时提供，遵循rfc3339标准格式，格式为yyyy-MM-DDTHH:mm:ss+TIMEZONE，yyyy-MM-DD表示年月日，T出现在字符串中，表示time元素的开头，HH:mm:ss表示时分秒，TIMEZONE表示时区（+08:00表示东八区时间，领先UTC 8小时，即北京时间）。例如：2015-05-20T13:29:35+08:00表示，北京时间2015年5月20日 13点29分35秒。

 deactivate_reason 　选填   string(150)

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

 attach 　选填   string

【自定义附加信息】 调用发券接口时品牌方使用 attach 字段主动设置的附加信息。微信支付不会解析该信息，仅在查询用户商品券和回调中原样返回。

注： 发券渠道多样，只有品牌方通过发券接口发放的券才会在查询和回调中携带此字段，其他渠道发放的券 attach 为空。

 channel_custom_info 　选填   string(1000)

【渠道自定义信息】 使用微信支付提供的其他渠道（比如「摇一摇有优惠」）发放商品券时，渠道可能会设置该渠道特定的自定义信息，请根据 send_channel 字段判断如何解析本字段。不同渠道的自定义信息格式不同，请根据对应渠道的文档解析。

 coupon_tag_info 　选填   object

【用户商品券标签信息】 用户商品券标签信息

属性

 coupon_tag_list 　选填   array[string]

【用户商品券标签列表】 用户商品券标签列表

可选取值

  • MEMBER:  会员标签，标识该用户商品券为会员券

  • MEMBER_ACTIVITY:  会员活动标签，标识该用户券为会员活动券

 member_tag_info 　选填   object

【会员标签信息】 当用户商品券标签列表中有MEMBER时，该字段必填

属性

 member_card_id 　选填   string

【会员卡模板ID】 通过商家名片会员API创建会员卡模板成功后，获得的会员卡模板ID

应答示例

200 OK

使用户券失效

1{
2  "coupon_code" : "Code_123456",
3  "coupon_state" : "DEACTIVATED",
4  "valid_begin_time" : "2025-08-02T00:00:00+08:00",
5  "valid_end_time" : "2025-08-31T23:59:59+08:00",
6  "receive_time" : "2025-08-02T00:00:00+08:00",
7  "send_request_no" : "MCHSEND202003101234",
8  "send_channel" : "API",
9  "confirm_request_no" : "MCHCONFIRM202003101234",
10  "confirm_time" : "2025-08-02T00:00:05+08:00",
11  "deactivate_request_no" : "MCHDEACTIVATE202003101234",
12  "deactivate_time" : "2025-08-03T12:01:00+08:00",
13  "deactivate_reason" : "商品已下线，使用户商品券失效",
14  "single_usage_detail" : {
15    "use_request_no" : "MCHUSE202003101234",
16    "use_time" : "2025-08-03T12:00:00+08:00",
17    "associated_order_info" : {
18      "transaction_id" : "4200000000123456789123456789"
19    },
20    "return_request_no" : "MCHRETURN202003101234",
21    "return_time" : "2025-08-03T12:01:00+08:00"
22  },
23  "product_coupon" : {
24    "product_coupon_id" : "1000000013",
25    "scope" : "ALL",
26    "type" : "DISCOUNT",
27    "usage_mode" : "SINGLE",
28    "single_usage_info" : {
29      "discount_coupon" : {
30        "threshold" : 10000,
31        "percent_off" : 20
32      }
33    },
34    "display_info" : {
35      "name" : "全场满100立打8折-新名字",
36      "image_url" : "https://wxpaylogo.qpic.cn/wxpaylogo/xxxxx/xxx",
37      "background_url" : "https://wxpaylogo.qpic.cn/wxpaylogo/xxxxx/xxx",
38      "detail_image_url_list" : [
39        "https://wxpaylogo.qpic.cn/wxpaylogo/xxxxx/xxx"
40      ]
41    },
42    "state" : "EFFECTIVE",
43    "out_product_no" : "Product_1234567890"
44  },
45  "stock" : {
46    "product_coupon_id" : "1000000013",
47    "stock_id" : "1000000013001",
48    "remark" : "8月工作日有效批次",
49    "coupon_code_mode" : "UPLOAD",
50    "coupon_code_count_info" : {
51      "total_count" : 0,
52      "available_count" : 0
53    },
54    "stock_send_rule" : {
55      "max_count" : 10000000,
56      "max_count_per_user" : 1
57    },
58    "single_usage_rule" : {
59      "coupon_available_period" : {
60        "available_begin_time" : "2025-08-01T00:00:00+08:00",
61        "available_end_time" : "2025-08-31T23:59:59+08:00",
62        "available_days" : 30,
63        "weekly_available_period" : {
64          "day_list" : [
65            "MONDAY",
66            "TUESDAY",
67            "WEDNESDAY",
68            "THURSDAY",
69            "FRIDAY"
70          ]
71        }
72      }
73    },
74    "usage_rule_display_info" : {
75      "coupon_usage_method_list" : [
76        "OFFLINE",
77        "MINI_PROGRAM",
78        "PAYMENT_CODE"
79      ],
80      "mini_program_appid" : "wx1234567890",
81      "mini_program_path" : "/pages/index/product",
82      "usage_description" : "工作日可用",
83      "coupon_available_store_info" : {
84        "description" : "所有门店可用，可使用小程序查看门店列表",
85        "mini_program_appid" : "wx1234567890",
86        "mini_program_path" : "/pages/index/store-list"
87      }
88    },
89    "coupon_display_info" : {
90      "code_display_mode" : "QRCODE",
91      "background_color" : "Color010",
92      "entrance_mini_program" : {
93        "appid" : "wx1234567890",
94        "path" : "/pages/index/product",
95        "entrance_wording" : "欢迎选购",
96        "guidance_wording" : "获取更多优惠"
97      },
98      "entrance_official_account" : {
99        "appid" : "wx1234567890"
100      }
101    },
102    "notify_config" : {
103      "notify_appid" : "wx4fd12345678"
104    },
105    "store_scope" : "NONE",
106    "sent_count_info" : {
107      "total_count" : 0,
108      "today_count" : 0
109    },
110    "state" : "SENDING"
111  },
112  "attach" : "any attach content"
113}
114

 

错误码

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

状态码

错误码

描述

解决方案

400

PARAM_ERROR

参数错误

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

400

INVALID_REQUEST

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

请参阅 接口规则

401

SIGN_ERROR

验证不通过

请参阅 签名常见问题

500

SYSTEM_ERROR

系统异常，请稍后重试

请稍后重试

400

INVALID_REQUEST

用户券当前状态不支持失效

请确认用户券处于可失效状态后再发起失效

400

INVALID_REQUEST

不允许失效多次优惠中的单张用户券

不允许失效多次优惠中的单张用户券

400

INVALID_REQUEST

单券使用模式的商品券批次，应该在「单券使用规则」中包含对应类型的优惠规则。对于文档中标记不应填写的优惠规则应删除。

请在「单券使用规则」中包含对应类型的优惠规则，并删除文档中标记不应填写的优惠规则。

400

INVALID_REQUEST

多次优惠使用模式的商品券批次，应该在「多次优惠使用规则」中包含对应类型的优惠规则，且数量与多次优惠的优惠次数相等

在「多次优惠使用规则」中包含对应类型的优惠规则，且数量与多次优惠的优惠次数相等

400

INVALID_REQUEST

单品满减券或单品折扣券不应在商品券中设置「满减券使用规则」或「折扣券使用规则」，而是应该在商品券批次中设置

请删除商品券中的「满减券使用规则」或「折扣券使用规则」，并在商品券批次中设置对应的优惠规则

403

NO_AUTH

品牌没有此接口权限

品牌没有此接口权限

400

INVALID_REQUEST

失效用户券单号已使用

补充失效单号

404

NOT_FOUND

用户券不存在

用户券不存在

400

INVALID_REQUEST

商品券支持APP核销时，必须提供「APP跳转路径」

请提供「APP跳转路径」参数

400

PARAM_ERROR

分页大小超出限制，请根据接口文档调整到允许的范围

请调整分页大小到规定范围

400

INVALID_REQUEST

商品券支持小程序核销时，必须提供「小程序AppID」

请提供「小程序AppID」

400

PARAM_ERROR

商品券批次ID不能为空

补充商品券批次ID

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

PARAM_ERROR

用户商品券Code不能为空

补充商品券Code参数

400

PARAM_ERROR

appid不能为空

补充appid

400

PARAM_ERROR

失效单号不能为空

补充失效单号

400

PARAM_ERROR

品牌ID不能为空

补充品牌ID参数

400

PARAM_ERROR

商品券ID不能为空

补充商品券ID参数

400

INVALID_REQUEST

用户券状态非法

用户券状态非法

400

PARAM_ERROR

参数错误

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

400

INVALID_REQUEST

Http头Content-Type值必须为application/json

需将Http头中的Content-Type值设置为application/json

400

INVALID_REQUEST

券已过期，不能再进行其他操作

券已过期，不能再进行其他操作

400

INVALID_REQUEST

券已被删除

检查用户券状态

 

LLM请查看llms.txt
开发文档(服务商)开发者社区微信开放平台微信公众平台腾讯客服
接口说明
请求参数
应答参数
错误码
反馈
目录
置顶
Powered By Tencent & Tenpay Copyright 2005-2026 Tenpay All Rights Reserved.
Powered By Tencent & Tenpay
Copyright 2005-2026 Tenpay All Rights Reserved.