核销用户券

更新时间：2025.08.04

品牌方可以通过本接口核销已经发放给用户的商品券

前置条件：已经给用户发券成功，且用户券当前可用

接口说明

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

请求方式：【POST】/v3/marketing/partner/product-coupon/users/{openid}/coupons/{coupon_code}/use

请求域名：【主域名】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

path 路径参数

coupon_code 　必填 string(40)

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

openid 　必填 string

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

body 包体参数

product_coupon_id 　必填 string

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

stock_id 　必填 string

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

appid 　必填 string

【公众账号AppID】请传入与当前调用接口服务商有绑定关系的AppID，支持小程序AppID与公众号AppID

use_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

【关联微信支付订单信息】券核销对应的微信支付订单信息

属性

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 时可忽略此字段

out_request_no 　必填 string(40)

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

sequential_coupon_index 　选填 integer

【次卡索引】本次核销对应的次卡轮次，从0开始计数，例如：

0 表示本次核销为首次核销
1 表示本次核销为第二次核销
以此类推

当且仅当商品券的 usage_mode 为 SEQUENTIAL 时必填，其他模式不应填写

brand_id 　必填 string

【品牌ID】微信支付为品牌方分配的唯一标识，该品牌应与服务商存在授权关系

请求示例

POST

1curl -X POST \
2  https://api.mch.weixin.qq.com/v3/marketing/partner/product-coupon/users/oh-394z-6CGkNoJrsDLTTUKiAnp4/coupons/123446565767/use \
3  -H "Authorization: WECHATPAY2-SHA256-RSA2048 mchid=\"1900000001\",..." \
4  -H "Accept: application/json" \
5  -H "Content-Type: application/json" \
6  -d '{
7    "product_coupon_id" : "1002323",
8    "stock_id" : "100232301",
9    "appid" : "wx233544546545989",
10    "use_time" : "2025-07-24T00:00+08:00",
11    "associated_order_info" : {
12      "transaction_id" : "4200000000123456789123456789",
13      "out_trade_no" : "trade_no_20250724123456",
14      "mchid" : "1234567890",
15      "sub_mchid" : "1234567890"
16    },
17    "out_request_no" : "MCHUSE202003101234",
18    "sequential_coupon_index" : 0,
19    "brand_id" : "120344"
20  }'
21

应答参数

200 OK

coupon_code 　必填 string(40)

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

coupon_state 　必填 string

【用户券状态】

可选取值

CONFIRMING: 待确认，用户券发放需要品牌方调用确认发放用户商品券接口后才能生效
PENDING: 已发放待生效，用户券已发放成功但尚未到达可用开始时间
EFFECTIVE: 已生效，用户券已成功发放且到达可用开始时间
USED: 已核销，用户券已核销
EXPIRED: 已过期，用户券已超过有效期，不再可用
DELETED: 已删除，用户主动删除该券
DEACTIVATED: 已失效，品牌方主动调用失效用户券接口使用户券失效

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

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

send_channel 　必填 string

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

可选取值

API: 品牌方自主发放，品牌方调用发券接口自行发放
BRAND_MANAGE: 摇一摇有优惠，通过摇一摇有优惠渠道发放
MERCHANT_CARD: 名片优惠，通过名片优惠渠道发放
MEMBER: 会员优惠，通过会员优惠渠道发放

confirm_request_no 　选填 string

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

confirm_time 　选填 string

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

deactivate_request_no 　选填 string

【失效请求单号】品牌方失效券请求时传入的的请求流水号。当且仅当 coupon_state 为 DEACTIVATED 时提供。

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

【失效原因】失效券的原因，当且仅当 coupon_state 为 DEACTIVATED 时提供

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小时，即北京时间）

associated_order_info 　选填 object

【券核销的微信支付订单信息】券核销对应的微信支付订单信息，当且仅当用户商品券状态 coupon_state 为 USED 时提供

属性

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 时可忽略此字段

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小时，即北京时间）

sequential_usage_detail 　选填 object

【次卡使用详情】当且仅当 usage_mode 为 SEQUENTIAL 时提供

属性

total_count 　必填 integer

【总可使用次数】本券总计可用次数

used_count 　必填 integer

【已使用次数】当前用户已使用次数

detail_item_list 　选填 array[object]

【轮次使用详情列表】次卡中具体每轮使用详情

属性

detail_state 　必填 string

【轮次使用详情状态】

可选取值

PENDING: 待生效，尚未到达可用开始时间
EFFECTIVE: 已生效，已到达可用开始时间
USED: 已核销
EXPIRED: 已过期，已超过有效期，不再可用
DELETED: 已删除，用户主动删除
DEACTIVATED: 已失效，品牌方主动调用失效用户券接口使用户券失效

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小时，即北京时间）

use_request_no 　选填 string

【核销请求单号】次卡轮次核销的请求流水号，当且仅当 detail_state 为 USED 时提供

use_time 　选填 string

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

associated_order_info 　选填 object

【核销的微信支付订单信息】次卡轮次核销对应的微信支付订单信息，当且仅当 detail_state 为 USED 时提供

属性

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 时可忽略此字段

return_request_no 　选填 string

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

return_time 　选填 string

delete_time 　选填 string

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

product_coupon 　必填 object

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

属性

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 且 scope 为 ALL 时提供，其他场景不提供。

属性

normal_coupon 　选填 object

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

属性

threshold 　必填 integer

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

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

discount_amount 　必填 integer

【固定减免金额】固定减免金额，单位为分。不得大于（可以等于） threshold

discount_coupon 　选填 object

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

属性

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 天内有效，最多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个单品

属性

out_product_no 　选填 string(40)

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

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 时提供，返回品牌方调用失效接口时传入的失效原因

brand_id 　必填 string

【品牌ID】微信支付为品牌方分配的唯一标识，该品牌应与服务商存在授权关系

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，微信支付系统发券时从中随机选取，当预存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 且 scope 为 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_list 　选填 object

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

属性

threshold 　必填 integer

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

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

discount_amount 　必填 integer

【固定减免金额】固定减免金额，单位为分。不得大于（可以等于） threshold

discount_coupon_list 　选填 object

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

属性

threshold 　必填 integer

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

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

percent_off 　必填 integer

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

exchange_coupon 　选填 object

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

属性

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

【批次开始时间】遵循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秒。

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

【固定减免金额】固定减免金额，单位为分。不得大于（可以等于） threshold

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种颜色，色值请参考下方说明。颜色取值为颜色图中的颜色名称，不填默认为 Color010 。

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

deactivate_reason 　选填 string

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

brand_id 　必填 string

【品牌ID】微信支付为品牌方分配的唯一标识，该品牌应与服务商存在授权关系

attach 　选填 string

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

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

channel_custom_info 　选填 string(1000)

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

brand_id 　必填 string

【品牌ID】微信支付为品牌方分配的唯一标识，该品牌应与服务商存在授权关系

应答示例

200 OK

1{
2  "coupon_code" : "123446565767",
3  "coupon_state" : "USED",
4  "valid_begin_time" : "2025-01-01T00:00+08:00",
5  "valid_end_time" : "2025-01-30T23:59:59+08:00",
6  "receive_time" : "2025-01-01T09:10:00+08:00",
7  "send_request_no" : "MCHSEND202003101234",
8  "send_channel" : "API",
9  "confirm_request_no" : "MCHCONFIRM202003101234",
10  "confirm_time" : "2025-01-20T13:29:35+08:00",
11  "deactivate_request_no" : "1002600620019090123143254436",
12  "deactivate_time" : "2025-01-20T13:29:35+08:00",
13  "deactivate_reason" : "商品已下线",
14  "single_usage_detail" : {
15    "use_request_no" : "MCHUSE202003101234",
16    "use_time" : "2025-07-20T13:29:35+08:00",
17    "associated_order_info" : {
18      "transaction_id" : "4200000000123456789123456789",
19      "out_trade_no" : "trade_no_20250724123456",
20      "mchid" : "1234567890",
21      "sub_mchid" : "1234567890"
22    },
23    "return_request_no" : "MCHRETURN202003101234",
24    "return_time" : "2025-07-20T14:29:35+08:00"
25  },
26  "sequential_usage_detail" : {
27    "total_count" : 10,
28    "used_count" : 3,
29    "detail_item_list" : [
30      {
31        "detail_state" : "USED",
32        "valid_begin_time" : "2025-07-24T00:00+08:00",
33        "valid_end_time" : "2025-07-30T23:59:59+08:00",
34        "use_request_no" : "MCHUSE202003101234",
35        "use_time" : "2025-07-20T13:29:35+08:00",
36        "associated_order_info" : {
37          "transaction_id" : "4200000000123456789123456789",
38          "out_trade_no" : "trade_no_20250724123456",
39          "mchid" : "1234567890",
40          "sub_mchid" : "1234567890"
41        },
42        "return_request_no" : "MCHRETURN202003101234",
43        "return_time" : "2025-07-20T14:29:35+08:00",
44        "delete_time" : "2025-07-20T14:29:35+08:00"
45      }
46    ]
47  },
48  "product_coupon" : {
49    "product_coupon_id" : "1002323",
50    "scope" : "ALL",
51    "type" : "NORMAL",
52    "usage_mode" : "SEQUENTIAL",
53    "single_usage_info" : {
54      "normal_coupon" : {
55        "threshold" : 10000,
56        "discount_amount" : 100
57      },
58      "discount_coupon" : {
59        "threshold" : 10000,
60        "percent_off" : 30
61      }
62    },
63    "sequential_usage_info" : {
64      "type" : "EQUAL",
65      "count" : 10,
66      "available_days" : 10,
67      "interval_days" : 1
68    },
69    "display_info" : {
70      "name" : "全场满100可减10元",
71      "image_url" : "https://wxpaylogo.qpic.cn/wxpaylogo/xxxxx/xxx",
72      "background_url" : "https://wxpaylogo.qpic.cn/wxpaylogo/xxxxx/xxx",
73      "detail_image_url_list" : [
74        "https://wxpaylogo.qpic.cn/wxpaylogo/xxxxx/xxx"
75      ],
76      "original_price" : 10000,
77      "combo_package_list" : [
78        {
79          "name" : "咖啡2选1",
80          "pick_count" : 3,
81          "choice_list" : [
82            {
83              "name" : "美式",
84              "price" : 10000,
85              "count" : 2,
86              "image_url" : "https://wxpaylogo.qpic.cn/wxpaylogo/xxxxx/xxx",
87              "mini_program_appid" : "wx4fd12345678",
88              "mini_program_path" : "/pages/index/index"
89            }
90          ]
91        }
92      ]
93    },
94    "out_product_no" : "example_out_product_no",
95    "state" : "AUDITING",
96    "deactivate_request_no" : "1002600620019090123143254436",
97    "deactivate_time" : "2025-06-20T13:29:35+08:00",
98    "deactivate_reason" : "商品已下架",
99    "brand_id" : "120344"
100  },
101  "stock" : {
102    "product_coupon_id" : "200000001",
103    "stock_id" : "123456789",
104    "remark" : "满减券",
105    "coupon_code_mode" : "UPLOAD",
106    "coupon_code_count_info" : {
107      "total_count" : 10000,
108      "available_count" : 999
109    },
110    "stock_send_rule" : {
111      "max_count" : 10000000,
112      "max_count_per_day" : 10000,
113      "max_count_per_user" : 1
114    },
115    "single_usage_rule" : {
116      "coupon_available_period" : {
117        "available_begin_time" : "2025-01-01T00:00:00+08:00",
118        "available_end_time" : "2025-10-01T00:00:00+08:00",
119        "available_days" : 10,
120        "wait_days_after_receive" : 1,
121        "weekly_available_period" : {
122          "day_list" : [
123            "MONDAY"
124          ],
125          "day_period_list" : [
126            {
127              "begin_time" : 60,
128              "end_time" : 86399
129            }
130          ]
131        },
132        "irregular_available_period_list" : [
133          {
134            "begin_time" : "2025-01-01T00:00:00+08:00",
135            "end_time" : "2025-10-01T00:00:00+08:00"
136          }
137        ]
138      },
139      "normal_coupon_list" : {
140        "threshold" : 10000,
141        "discount_amount" : 100
142      },
143      "discount_coupon_list" : {
144        "threshold" : 10000,
145        "percent_off" : 30
146      },
147      "exchange_coupon" : {
148        "threshold" : 10000,
149        "exchange_price" : 100
150      }
151    },
152    "sequential_usage_rule" : {
153      "coupon_available_period" : {
154        "available_begin_time" : "2025-01-01T00:00:00+08:00",
155        "available_end_time" : "2025-10-01T00:00:00+08:00",
156        "wait_days_after_receive" : 1,
157        "weekly_available_period" : {
158          "day_list" : [
159            "MONDAY"
160          ],
161          "day_period_list" : [
162            {
163              "begin_time" : 60,
164              "end_time" : 86399
165            }
166          ]
167        },
168        "irregular_available_period_list" : [
169          {
170            "begin_time" : "2025-01-01T00:00:00+08:00",
171            "end_time" : "2025-10-01T00:00:00+08:00"
172          }
173        ]
174      },
175      "normal_coupon_list" : [
176        {
177          "threshold" : 10000,
178          "discount_amount" : 100
179        }
180      ],
181      "discount_coupon_list" : [
182        {
183          "threshold" : 10000,
184          "percent_off" : 30
185        }
186      ],
187      "exchange_coupon_list" : [
188        {
189          "threshold" : 10000,
190          "exchange_price" : 100
191        }
192      ],
193      "special_first" : false
194    },
195    "usage_rule_display_info" : {
196      "coupon_usage_method_list" : [
197        "MINI_PROGRAM"
198      ],
199      "mini_program_appid" : "wx1234567890",
200      "mini_program_path" : "/pages/index/product",
201      "app_path" : "https://www.example.com/jump-to-app",
202      "usage_description" : "全场可用",
203      "coupon_available_store_info" : {
204        "description" : "可在上海市区的所有门店使用，详细列表参考小程序内信息为准",
205        "mini_program_appid" : "wx1234567890",
206        "mini_program_path" : "/pages/index/store-list"
207      }
208    },
209    "coupon_display_info" : {
210      "code_display_mode" : "QRCODE",
211      "background_color" : "Color010",
212      "entrance_mini_program" : {
213        "appid" : "wx1234567890",
214        "path" : "/pages/index/product",
215        "entrance_wording" : "欢迎选购",
216        "guidance_wording" : "获取更多优惠"
217      },
218      "entrance_official_account" : {
219        "appid" : "wx1234567890"
220      },
221      "entrance_finder" : {
222        "finder_id" : "gh_12345678",
223        "finder_video_id" : "UDFsdf24df34dD456Hdf34",
224        "finder_video_cover_image_url" : "https://wxpaylogo.qpic.cn/wxpaylogo/xxxxx/xxx"
225      }
226    },
227    "notify_config" : {
228      "notify_appid" : "wx4fd12345678"
229    },
230    "store_scope" : "SPECIFIC",
231    "sent_count_info" : {
232      "total_count" : 100,
233      "today_count" : 10
234    },
235    "state" : "SENDING",
236    "deactivate_request_no" : "1002600620019090123143254436",
237    "deactivate_time" : "2025-01-01T00:00+08:00",
238    "deactivate_reason" : "批次信息有误，重新创建",
239    "brand_id" : "120344"
240  },
241  "attach" : "example_attach",
242  "channel_custom_info" : "example_channel_custom_info",
243  "brand_id" : "120344"
244}
245

错误码

公共错误码

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

业务错误码

状态码	错误码	描述	解决方案
400	INVALID_REQUEST	传入参数不符合业务规则	请参考文档中对每个字段的要求以及组合要求，确认请求参数是否满足
403	NO_AUTH	缺少业务相关权限	请确认已开通商品券权限
403	NOT_ENOUGH	用户券当前无法使用	请确认用户券当前是否处于可用状态
404	NOT_FOUND	未找到 product_coupon_id 对应的商品券	请确认 product_coupon_id 存在且属于当前品牌
404	NOT_FOUND	未找到 stock_id 对应的商品券批次	请确认 stock_id 存在且属于当前商品券
404	NOT_FOUND	未找到 coupon_code 对应的用户商品券	请确认 coupon_code 存在且属于当前商品券批次，且已发放给用户
429	RATELIMIT_EXCEEDED	请求超过接口频率限制	请稍后使用原参数重试

文档是否有帮助

更多支持

开发文档(商户)开发文档(V2版)开发者社区微信开放平台微信公众平台腾讯客服