失效商品券

更新时间：2025.08.20

品牌方可以通过该接口使某个商品券失效。

注意：

失效商品券会失效商品券所有批次。
失效商品券会同步终止该商品券所有投放渠道和活动，不会有新的用户领券事件，但历史已经通过该商品券对应的批次发放的用户商品券仍然有效。

前置条件：已创建商品券

接口说明

支持商户：【品牌商户】

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

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

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

请求参数

Header HTTP头参数

Authorization 　必填　string

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

Accept 　必填　string

请设置为application/json

Content-Type 　必填　string

请设置为application/json

Wechatpay-Serial 　必填　string

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

path 路径参数

product_coupon_id 　必填 string

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

body 包体参数

out_request_no 　必填 string(40)

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

deactivate_reason 　必填 string(150)

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

请求示例

POST

1curl -X POST \
2  https://api.mch.weixin.qq.com/brand/marketing/product-coupon/product-coupons/200000001/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    "out_request_no" : "34657_20250101_123456",
9    "deactivate_reason" : "批次信息有误，重新创建"
10  }'
11

应答参数

200 OK

product_coupon_id 　必填 string(40)

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

scope 　必填 string

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

可选取值

ALL: 全场券，此时券类型 type 仅可配置为 NORMAL 或 DISCOUNT
SINGLE: 单品券，此时券类型 type 配置不受限制，即可配置为 NORMAL、DISCOUNT 或 EXCHANGE

type 　必填 string

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

可选取值

NORMAL: 满减券
DISCOUNT: 折扣券
EXCHANGE: 换购券，仅在 scope 为 SINGLE 时可配置

usage_mode 　必填 string

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

可选取值

SINGLE: 单券，即用户只能使用一次，使用后券失效
SEQUENTIAL: 多次优惠，即用户可以按顺序多次使用，每次核销成功后会发放下一次优惠机会，直到用完为止

single_usage_info 　选填 object

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

属性

normal_coupon 　选填 object

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

属性

threshold 　必填 integer

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

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

discount_amount 　必填 integer

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

discount_coupon 　选填 object

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

属性

threshold 　必填 integer

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

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

percent_off 　必填 integer

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

sequential_usage_info 　选填 object

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

属性

type 　必填 string

【多次优惠规则类型】多次优惠规则类型

可选取值

INCREMENTAL: 阶梯优惠，除首次外，剩余次数优惠力度递增
EQUAL: 等额优惠，除首次外，剩余次数优惠力度不变

count 　必填 integer

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

available_days 　必填 integer

【多次优惠有效天数】用户的多次优惠生效后 N 天内有效，最少3天，最多365天

interval_days 　选填 integer

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

间隔 0 天表示不限制，使用后当天仍然可以继续使用下一次优惠
间隔 1 天表示使用后当天不再可用，下一次优惠需要等到次日 00:00:00 才能使用
间隔 2 天表示使用后当天和次日不再可用，下一次优惠需要等到第三天 00:00:00 才能使用
依此类推……

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

display_info 　必填 object

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

属性

name 　必填 string(15)

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

image_url 　必填 string

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

请参考商品券图片设计规范进行设计
要求图片宽高比1:1，建议尺寸1080*1080
大小不超过2M
格式为透明png格式
需要注意保留透明边距（上下左右各120px）

background_url 　必填 string

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

要求图片宽高比65:77，建议尺寸1170*1326
大小不超过2M
格式jpg
需要注意保留「商品名称」与「商品图」的安全区域

detail_image_url_list 　选填 array[string]

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

要求图片宽高比65:77，建议尺寸1170*1326
大小不超过2M
格式jpg

original_price 　选填 integer

【商品原价】单位为分，当且仅当 scope 为 SINGLE 必填，用于对外展示，其他优惠范围不应填写。

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个单品

属性

name 　必填 string(15)

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

price 　必填 integer

【单品价格】单位为分

count 　必填 integer

【单品数量】最多99个

image_url 　选填 string

【单品图片】单品图片URL地址，仅支持通过图片上传接口获取的图片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

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

deactivate_time 　选填 string

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

deactivate_reason 　选填 string

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

应答示例

200 OK

1{
2  "product_coupon_id" : "1002323",
3  "scope" : "ALL",
4  "type" : "NORMAL",
5  "usage_mode" : "SEQUENTIAL",
6  "single_usage_info" : {
7    "normal_coupon" : {
8      "threshold" : 10000,
9      "discount_amount" : 100
10    },
11    "discount_coupon" : {
12      "threshold" : 10000,
13      "percent_off" : 30
14    }
15  },
16  "sequential_usage_info" : {
17    "type" : "EQUAL",
18    "count" : 10,
19    "available_days" : 10,
20    "interval_days" : 1
21  },
22  "display_info" : {
23    "name" : "全场满100可减10元",
24    "image_url" : "https://wxpaylogo.qpic.cn/wxpaylogo/xxxxx/xxx",
25    "background_url" : "https://wxpaylogo.qpic.cn/wxpaylogo/xxxxx/xxx",
26    "detail_image_url_list" : [
27      "https://wxpaylogo.qpic.cn/wxpaylogo/xxxxx/xxx"
28    ],
29    "original_price" : 10000,
30    "combo_package_list" : [
31      {
32        "name" : "咖啡2选1",
33        "pick_count" : 3,
34        "choice_list" : [
35          {
36            "name" : "美式",
37            "price" : 10000,
38            "count" : 2,
39            "image_url" : "https://wxpaylogo.qpic.cn/wxpaylogo/xxxxx/xxx",
40            "mini_program_appid" : "wx4fd12345678",
41            "mini_program_path" : "/pages/index/index"
42          }
43        ]
44      }
45    ]
46  },
47  "out_product_no" : "Product_1234567890",
48  "state" : "AUDITING",
49  "deactivate_request_no" : "1002600620019090123143254436",
50  "deactivate_time" : "2025-06-20T13:29:35+08:00",
51  "deactivate_reason" : "商品已下架"
52}
53

错误码

公共错误码

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

业务错误码

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

文档是否有帮助

更多支持

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