失效商品券批次

更新时间：2025.08.28

品牌方可以通过该接口使已经创建的某个商品券批次失效。

注意：

调用本接口只会失效单个批次，商品券本身以及其他商品券批次不受影响。
失效商品券批次后，该批次不会有新的用户领券事件，但历史已经通过该批次发放的用户商品券仍然有效。

前置条件：已创建商品券批次

接口说明

支持商户：【品牌商户】

请求方式：【POST】/brand/marketing/product-coupon/product-coupons/{product_coupon_id}/stocks/{stock_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】商品券的唯一标识，创建商品券时由微信支付生成

stock_id 　必填 string

【批次ID】商品券批次的唯一标识，商品券批次创建时由微信支付生成（可使用创建商品券或添加商品券批次创建），请确保该批次属于 product_coupon_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/stocks/123456789/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】商品券的唯一标识，由微信支付生成

stock_id 　必填 string(40)

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

remark 　选填 string(20)

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

coupon_code_mode 　必填 string

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

可选取值

WECHATPAY: 微信支付随机生成，发券时由微信支付系统自动随机生成券码，品牌方无需干预，微信支付随机生成的券Code长度限制为40个字符以内
UPLOAD: 品牌方预上传Code，品牌方需先使用预上传券Code API上传自定义Code，微信支付系统发券时从中随机选取，当预存Code不足时可能影响发券，品牌应及时补充
API_ASSIGN: 品牌方自行指定，品牌方通过发券API自行发券时指定，微信支付系统不再进行自动分配。特别注意：这种模式的商品批次只可由品牌方自行发券，无法在摇一摇有优惠等微信支付渠道投放

coupon_code_count_info 　选填 object

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

属性

stock_send_rule 　必填 object

【发放规则】发放规则

属性

single_usage_rule 　选填 object

【单券使用规则】当且仅当 usage_mode 为 SINGLE 时提供，其他场景不提供

属性

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

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

available_days 　选填 integer

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

生效当天内有效填 1
生效后2天内有效填 2
依此类推……

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

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

wait_days_after_receive 　选填 integer

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

领券后当天开始生效则无需填写
领券后第二天开始生效则填写 1

用户在有效期开始前领取商品券，则从有效期第1天开始计算天数，用户在有效期内领取商品券，则从领取当天开始计算天数。无论用户何时领取商品券，商品券在活动有效期结束后均不可用。需配合 available_days 一同填写，不可单独填写。

weekly_available_period 　选填 object

【每周固定可用时间】每周固定可用时间

属性

day_list 　选填 array[string]

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

可选取值

MONDAY: 周一可用
TUESDAY: 周二可用
WEDNESDAY: 周三可用
THURSDAY: 周四可用
FRIDAY: 周五可用
SATURDAY: 周六可用
SUNDAY: 周日可用

day_period_list 　选填 array[object]

【当天可用时间段】生效当天特定时间段内有效，可以配置多个时间段。最多可以配置 2 个时间段。不配置则全天可用。配置此字段后 day_list 字段必填

属性

begin_time 　必填 integer

【当天可用开始时间】当天可用时间距离当天 00:00::00 的秒数，如 60 表示当天 00:01:00 开始可用

end_time 　必填 integer

【当天可用结束时间】当天结束可用时间距离当天 00:00:00 的秒数，如 86399 表示当天 23:59:59 结束可用

irregular_available_period_list 　选填 array[object]

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

属性

normal_coupon 　选填 object

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

属性

threshold 　必填 integer

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

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

discount_amount 　必填 integer

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

discount_coupon 　选填 object

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

属性

threshold 　必填 integer

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

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

percent_off 　必填 integer

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

exchange_coupon 　选填 object

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

属性

threshold 　必填 integer

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

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

exchange_price 　必填 integer

【固定兑换价格】单位为分

sequential_usage_rule 　选填 object

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

属性

coupon_available_period 　必填 object

【多次优惠可核销时间】确定用户领取多次优惠后在什么时间段内可以核销，多次优惠可核销时间不会超过多次优惠有效天数（多次优惠商品券中配置的 sequential_usage_info.available_days 字段）

属性

available_begin_time 　必填 string

available_end_time 　必填 string

wait_days_after_receive 　选填 integer

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

领券后当天开始生效则无需填写
领券后第二天开始生效则填写 1

weekly_available_period 　选填 object

【每周固定可用时间】每周固定可用时间

属性

day_list 　选填 array[string]

可选取值

MONDAY: 周一可用
TUESDAY: 周二可用
WEDNESDAY: 周三可用
THURSDAY: 周四可用
FRIDAY: 周五可用
SATURDAY: 周六可用
SUNDAY: 周日可用

day_period_list 　选填 array[object]

属性

begin_time 　必填 integer

【当天可用开始时间】当天可用时间距离当天 00:00::00 的秒数，如 60 表示当天 00:01:00 开始可用

end_time 　必填 integer

【当天可用结束时间】当天结束可用时间距离当天 00:00:00 的秒数，如 86399 表示当天 23:59:59 结束可用

irregular_available_period_list 　选填 array[object]

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

属性

normal_coupon_list 　选填 array[object]

【满减券使用规则】当且仅当 type 为 NORMAL 时必填，其他类型不应填写，元素个数应等于 sequential_usage_info.count

属性

threshold 　必填 integer

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

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

discount_amount 　必填 integer

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

discount_coupon_list 　选填 array[object]

【折扣券使用规则】当且仅当 type 为 DISCOUNT 时必填，其他类型不应填写，元素个数应等于 sequential_usage_info.count

属性

threshold 　必填 integer

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

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

percent_off 　必填 integer

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

exchange_coupon_list 　选填 array[object]

【兑换券使用规则】当且仅当 type 为 EXCHANGE 时必填，其他类型不应填写，元素个数应等于 sequential_usage_info.count

属性

threshold 　必填 integer

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

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

exchange_price 　必填 integer

【固定兑换价格】单位为分

special_first 　选填 boolean

【多次优惠是否提供首笔特惠】默认情况下为 false，多次优惠各轮优惠力度应保持递增(INCREMENTAL)或等额(EQUAL)。

当此字段设置为 true 时，首轮优惠不受此约束，且必须优于第二轮的优惠力度

usage_rule_display_info 　必填 object

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

属性

coupon_usage_method_list 　必填 array[string]

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

可选取值

OFFLINE: 线下滴码核销，点击券“立即使用”跳转展示券二维码详情
MINI_PROGRAM: 线上小程序核销，点击券“立即使用”跳转至配置的商家小程序（需要添加小程序AppID和Path）
APP: APP核销，在商家APP内核销
PAYMENT_CODE: 微信支付付款码核销，点击券“立即使用”跳转至微信支付钱包付款码

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跳转路径】品牌方APP跳转路径，在 coupon_usage_method_list 中包含 APP 时必填。

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

coupon_display_info 　必填 object

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

属性

code_display_mode 　必填 string

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

可选取值

INVISIBLE: 不展示Code
BARCODE: 条形码
QRCODE: 二维码

background_color 　选填 string

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

entrance_mini_program 　选填 object

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

属性

entrance_official_account 　选填 object

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

属性

entrance_finder 　选填 object

【视频号入口】展示跳转视频号的入口

属性

notify_config 　必填 object

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

属性

store_scope 　必填 string

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

可选取值

NONE: 无关联门店，该批次对外不展示可用门店信息
ALL: 所有门店可用，该批次在品牌下的所有门店可用，品牌无需为该批次关联门店列表
SPECIFIC: 特定门店可用，品牌需调用关联门店接口关联门店，关联后该批次在关联的门店可用

sent_count_info 　必填 object

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

属性

state 　必填 string

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

可选取值

AUDITING: 审批中
SENDING: 发放中
PAUSED: 已暂停
STOPPED: 已停止，当前已到达结束时间
DEACTIVATED: 已失效，品牌方主动调用失效接口使批次失效

deactivate_request_no 　选填 string

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

deactivate_time 　选填 string

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

deactivate_reason 　选填 string

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

应答示例

200 OK

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

错误码

公共错误码

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

业务错误码

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

文档是否有帮助

更多支持

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