---
url: "https://pay.weixin.qq.com/doc/brand/4016950459.md"
title: "常见问题"
doc_id: 4016950459
---

>更新时间：2025.12.23

## 一、商品券管理

### Q：为什么创建商品券时，单券-全场商品可用券的场景下，【优惠力度】 `single_usage_info` 是在商品信息中配置，单券-部分商品可用券场景下又是在【批次】 `stock` 里配置优惠力度？

A：

全场商品可用券的【优惠力度】 ` single_usage_info` 属于商品信息中的一部分，不同优惠力度的全场商品可用券代表不同的商品，批次则主要负责管理的是库存、预算、有效时间等信息。

例：“A饮品全场七折券”、“B饮品全场八折券”，购买不同的饮品就享受不同的折扣优惠。

部分商品可用券的【优惠力度】 `single_usage_rule` 属于【批次信息】 `stock` 中的一部分，同一个商品在不同批次可以设置不同的优惠力度，以实现将不同优惠力度投放给不同目标人群。

例：“某某饮品优惠券”，创建了不同优惠力度的批次，不同目标人群领券后购买同一商品，能享受到的优惠不同。

### Q：商品券的批次需要满足什么条件才能用于创建投放计划？

A：需要满足以下条件：

1、【批次开始时间】 `available_begin_time` 与【批次结束时间】 `available_end_time` 间隔大于5天。

2、【发放次数总上限】 `max_count` 需≥10000。

3、【券使用方式列表】 `coupon_usage_method_list` 不能包含“OFFLINE:  线下滴码核销”

更多投放计划字段详情可参考：[投放计划配置指引-字段介绍](https://pay.weixin.qq.com/doc/v3/partner/4016111064.md#%E5%AD%97%E6%AE%B5%E4%BB%8B%E7%BB%8D)

### Q：商品券各个字段在客户端的展示效果是怎样的？

A：可参考[产品示例图（单券）](https://pay.weixin.qq.com/doc/v3/partner/4015989376.md#2.1%E3%80%81%E5%95%86%E5%93%81%E5%88%B8%E6%A8%A1%E5%BC%8F)和[产品示例图（多次优惠）](https://pay.weixin.qq.com/doc/v3/partner/4016438787.md#2.1%E3%80%81%E5%95%86%E5%93%81%E5%88%B8%E6%A8%A1%E5%BC%8F)

### Q：创建商品券设置【券可核销时间】 `coupon_available_period` 时，设置了多种可核销的时间段，券的实际可核销时间会如何取值？

A：会取各时间段的“交集”时间，具体可参考文档：[商品券可核销时间规则说明](https://pay.weixin.qq.com/doc/v3/partner/4016675999.md)

### Q：调用“创建商品券”接口报错：appid非法

A：请检查appid是否为品牌/服务商关联的appid。

品牌关联appid：

可选择以下两种路径之一进行关联，关联的前提为已通过微信认证的appid：

- 路径一：小程序、服务号、公众号、APP类型的都可以按以下步骤进行关联：

  - 步骤1：品牌方在【品牌经营平台-账号管理-下单appid管理】页面，点击“关联appid”。

  - 步骤2：品牌经营平台完成关联后，将在次日生效，请耐心等待。

![](https://gtimg.wechatpay.cn/resource/xres/mmpaydoc/static/img/3ce5541b52c36adeb1c6d49ebe54673e.png)

- 路径二：小程序、APP类型的appid，如果是用于支付交易的appid，可通过“交易连接名片”功能进行关联，两种关联方式：

  - 方式一：服务商通过商家名片下的“[交易连接名片](https://pay.weixin.qq.com/doc/v3/partner/4016985845.md)”功能，为品牌方关联appid。（目前只支持服务商模式）

  - 方式二：品牌方在【品牌经营平台-商家名片-交易链接名片】页面，点击“添加”关联appid。

![](https://gtimg.wechatpay.cn/resource/xres/mmpaydoc/static/img/3776e137fffea5368b2935f41966911a.png)

服务商关联appid（目前只支持服务商模式）：

服务商可登录[服务商平台](https://pay.weixin.qq.com/index.php/partner/public/home)，通过路径【产品中心 -\> APPID账号管理 -> 我关联的APPID账号】来查看所有绑定的APPID账号。

在该页面可以新增关联appid，具体流程请参考[服务商商户号与AppID账号关联管理](https://kf.qq.com/faq/200520fueQrI200520aQf6Rr.html)。

![](https://gtimg.wechatpay.cn/resource/xres/mmpaydoc/static/img/efd1aa570c8665e47bf1abce12456a9a.png)

### Q：调用“创建商品券”接口报错：appid不存在

A：appid本身的值是否正确，例如：不能填写不存在的appid；检查传的值是否带有空格之类不属于appid的特殊符号等。

### Q：商品券在什么场景下适合使用预上传Code的【券Code分配模式】 `coupon_code_mode`？

A：商户侧已有一套券code（券码）核销系统，微信生成自动生成的券码无法识别，需要使用自己系统生成的code才能识别时，适合使用该模式。

### Q：调用“创建商品券”接口时，【固定减免金额】 `discount_amount`、【固定减免百分比】 `percent_off`、【固定兑换价格】 `exchange_price` 是否可以为0？

A：【固定减免金额】 `discount_amount`、【固定减免百分比】 `percent_off` 不能为0，【固定兑换价格】 `exchange_price` 可以为0。

### Q：调用“修改商品券”接口报错：当前访问对象不存在，请确认ID是否合法、属于当前品牌且由当前服务商创建

A：【商品券ID】 `product_coupon_id` 必须为对应品牌和服务商创建的商品券，如果【商品券ID】 `product_coupon_id` 本身没有传错值，则检查品牌ID与服务商商户号是否与创券时一致。

### Q：调用“创建商品券”接口传了【背景颜色】 `background_color`，但没有生效是什么原因？

A：请检查【背景颜色】 `background_color` 传值是否正确，并且只能为接口参数限制的10种颜色。

### Q：商品券的批次号是品牌下唯一的吗？

A：是全局唯一的。

### Q：商品券（多次优惠）调用“创建商品券”/“添加商品券批次组”时，是否可以给批次组中的不同批次设置不同的商品券类型？例如第一次用满减券，第二次、第三次用折扣券。

A：不支持，【商品券类型】 `type` 是在创建商品券时设置在"商品券"维度的信息，不是"批次组/批次"维度单独设置的信息，因此商品券下所有批次的商品券类型都是统一的。

## 二、商品券批次管理

### Q：调用“创建商品券”/“添加商品券批次”/“添加商品券批次组”接口时，设置的【券生效后N天内可用】 `available_days` 和【领券后需等待N天才生效】 `wait_days_after_receive`，其中的天数是按自然日计算的，还是24小时计算的？

A：按自然日计算。例如：

- “1天内可用”，就是发放当天可用，过了凌晨12点未使用，券就会过期；

- “1天后才生效”，就是发放后，当天过了凌晨12点，券就会开始生效。


### Q：调用“修改商品券批次发放预算”/“修改商品券批次组发放预算”接口减少【目标批次发放次数总上限】 `target_max_count`，若此时已上传的code数量超过批次的减少后的总上限，是否会有影响？

A：无影响，若后续修改扩充批次(组)的【目标批次发放次数总上限】 `target_max_count`，将沿用已上传的券code用于发券。

### Q：调用“修改商品券批次发放预算”/“修改商品券批次组发放预算”接口，报错：商品券批次当前每日发放次数上限与真实值不符

A：请求参数中【当前批次发放次数总上限】 `current_max_count` 的值与该批次(组)当前实际生效的每日发放次数上限不一致，可调用"查询商品券指定批次"接口确认批次(组)当前的每日发放次数上限。

### Q：多次调用商品券的“批次关联门店”接口，关联的门店列表的取值逻辑是怎样的？

A：取多次关联记录的合集，即在原有记录上追加新的记录，例如第一次调用接口关联A、B两个门店，第二次关联B、C两个门店，则该批次已关联的门店为A、B、C三个门店。

### Q：提升商品券发放预算的上限后，调用“上传预存code”接口返回：上传的自定义code已达上限

A：修改批次发放预算后，后台有缓存，短时间内调用“上传预存code”接口可能访问到修改前的发放预算配置，因此返回报错，建议等待十分钟后再调用“上传预存code”接口。

### Q：调用“修改商品券批次发放预算”/“修改商品券批次组发放预算”接口报错：商品券批次总预算旧值已无效，请使用最新的投放预算值

A：【当前批次发放次数总上限】 `current_max_count` 不是批次当前的发放次数总上限，建议调用“查询商品券指定批次”接口确认批次当前的【发放次数总上限】 `max_count`

### Q：商品券（多次优惠）调用“创建商品券”/“添加商品券批次组”时，是否可以给批次组中的不同批次设置不同的有效期？

A：不支持，【券可核销时间】 `coupon_available_period` 是设置在"批次组"维度的信息，因此批次组中各个批次的有效期都是统一的。

### Q：商品券（多次优惠）设置了【多次优惠使用间隔天数】 `interval_days`，用户领券后，各批次的有效期会如何计算的？

A：各批次的有效期从用户领取批次组开始，按【券可核销时间】 `coupon_available_period` 中设置的时间计算，无论是否设置了使用间隔天数，券有效期的时间范围都是一致的，使用间隔天数限制的是用户多次使用券的间隔时间，非券本身的有效期。

### Q：调用“修改商品券批次”接口报错：批次正在修改中，请稍后重试

A：该报错指在本次调用接口前，已调用过“修改商品券批次”接口，且提交的信息目前还处于审核中的状态，需等待审通过后才能再次修改。

### Q：调用“预上传券CODE”接口报错：批次创建处理中，暂不能上传Code

A：创券成功后，建议间隔5分钟后再调用“预上传券CODE”接口。

### Q：调用“修改商品券批次”接口将商品券批次的【可用门店范围】 `store_scope` 从"SPECIFIC: 特定门店可用"改成"ALL: 所有门店可用"后，是否还需要去取消历史已关联的门店？

A：不需要

### Q：商品券/商品券批次的金额信息、有效期信息是否支持修改？

A：不支持，“修改商品券”只能修改商品券的展示信息（ `display_info`【展示信息】），“修改商品券批次”接口只能修改商品券的展示信息（ `usage_rule_display_info`【券使用规则展示信息】、 `coupon_display_info`【用户商品券展示信息】）、通知配置（ `notify_config`【事件通知配置】）。

金额信息、有效期信息无法修改，只能通过调用“创建商品券”/“创建商品券批次”接口，在创建新的商品券批次时设置。

## 三、商品券发放

### Q：测试人员通过预览投放计划的二维码，扫码进入领券页面，点击领取时提示“领取失败，请稍后再试”是什么原因？

A：请检查以下几点：

1、投放计划配置的商品券批次库存是否充足。

注意：调用“创建商品券/添加商品券批次(组)”接口时设置的 【券Code分配模式】若为: "品牌方预上传Code"（ `"coupon_code_mode":"UPLOAD"`）,则需通过调用【预上传券Code】接口补充库存，code不足将无法发券。

2、测试场景会展示两个同样的领券页面，第一张领取后，接着领取第二张会报该错误（正式环境会展示不同的券，不会有该问题），可重新扫码进入新的测试领券的页面。

### Q：调用“向用户发放商品券”接口报错：发券的公众账号ID无效

A：请检查以下几点：

1、服务商模式下，发券使用的appid需要与服务商商户号有绑定关系

2、品牌模式下，发券使用的appid需要与品牌ID有绑定关系

### Q：调用“向用户发放商品券”接口报错：传入的OpenID不合法

A：请按以下几点进行排查：

1、openid本身是否填写正确，不能填写一个不存在的openid。

2、需要是调用接口传入的appid对应的获取的openid。

3、openid对应的【用户UnionID】 `unionid` 需要与"商品券回调通知"中返回的【用户UnionID】 `unionid` 一致，确保是同一个用户。

### Q：“向用户发放商品券”接口中，【用户商品券标签信息】 `coupon_tag_info` 的作用是怎样的？不传是否会有影响？

A：领券后，用户如果为对应【会员卡模板ID】 `member_card_id` 的会员，在商家名片的页面查看券时，券会显示一个“会员”的标签。不传则不显示“会员”的标签，示例图如下：

![](https://gtimg.wechatpay.cn/resource/xres/mmpaydoc/static/img/6b4e464332d51e5a4dbfa5619b8a361c.png)

### Q：小程序发券组件的弹框支持展示多张商品券吗？

A：不支持

### Q：调用“向用户发放商品券”/“向用户发放商品券批次组”/“调起小程序发券组件”发放商品券时是否可以同时发多张券？

A：不支持同时发多张券，一次只能发一张。

### Q：使用相同的参数调用小程序发券组件的“向用户预发放商品券”/“向用户预发放商品券批次组”接口，返回的token是否相同？是否会进行幂等处理？

A：获取token的流程不会进行幂等处理，每次调用接口都会返回不同的token，每个token的有效期为5分钟，过期后需要重新调用接口获取。

### Q：发放商品券时，是否会校验重复发券？校验的规则是怎样的？

A：接口会根据用户(unionid)+stock\_id+send\_request\_no校验实际发给用户的是否发放的为同一张券/同一券组。

注意：一个微信账号只会有一个unionid，同一微信账号在不同的appid下会有不同的openid，如果不同的appid+openid指向的是同一个unionid，即为同一用户领券。

## 四、商品券回调通知

### Q：商品券事件通知地址是否可以在平台上手动配置？

A：不可以，只能通过“设置商品券事件通知地址（[品牌模式](https://pay.weixin.qq.com/doc/brand/4015736293.md)/[服务商模式](https://pay.weixin.qq.com/doc/v3/partner/4015781286.md)）”接口进行配置。

### Q：领取商品券后，为什么无法接收到“商品券回调通知”？

A：请参考以下几点进行排查：

1、回调地址配置类问题

1.1、地址配置错误

- 商户在“设置商品券事件通知地址”接口中配置的【通知URL地址】 `notify_url` 存在拼写错误（如域名错写、路径漏填）；

- 地址未使用公网可访问的 HTTPS 协议（微信支付强制要求回调地址为 HTTPS）；

- 使用了内网地址（如 `192.168.x.x`、 `localhost`），微信支付服务器无法穿透内网访问。


1.2、地址未完成备案 / 解析异常

- 回调地址对应的域名未完成工信部 ICP 备案（国内服务器必选，境外服务器虽无需备案，但需确保域名解析正常）；

- 域名 DNS 解析失效（如解析记录过期、未配置正确的 A/AAAA 记录），导致微信支付服务器无法解析到商户服务器 IP。


2、网络与服务器连通性问题

2.1、商户服务器防火墙 / 安全组拦截

- 商户服务器的防火墙（如 Linux iptables、Windows 防火墙）或云服务商安全组，未开放微信支付回调通知的入站请求，需对微信支付回调IP开通白名单，微信支付回调IP列表可查看：[回调处理逻辑注意事项](https://pay.weixin.qq.com/doc/v3/partner/4012082570.md#2.-%E5%9B%9E%E8%B0%83%E5%A4%84%E7%90%86%E9%80%BB%E8%BE%91%E6%B3%A8%E6%84%8F%E4%BA%8B%E9%A1%B9)；


| 商品券回调通知IP白名单 | 商品券回调通知IP白名单 | 商品券回调通知IP白名单 |
| --- | --- | --- |
| 81.71.199.64 | 81.71.198.25 | 81.71.199.59 |

- 服务器开启了 CC 攻击防护、WAF（Web 应用防火墙）等安全策略，误将微信支付的回调请求判定为恶意请求并拦截。


2.2、网络链路故障

- 商户服务器所在网络存在链路丢包、延迟过高（如超过 3 秒），导致微信支付发送的通知请求超时；

- 商户使用的 CDN 或反向代理（如 Nginx、Cloudflare）配置异常，未将回调请求正确转发至后端业务服务器。


3、其他场景

- 如果商户没有设置apiv3key微信支付不会发送回调通知。

- 如果同一个回调地址有些回调能收到，有些回调收不到，请确认下该回调地址是否有多个服务器配置，是否只有某部分机器能收到，另一部分的机器无法收到，再排查未接收到回调的服务器是否正常。


### Q：应答“商品券回调通知”和“确认发放用户商品券”是否有先后要求，是否一定要求应答成功才能确认发券？

A：无硬性的先后要求，可以先确认发券，再应答回调通知，但要注意回调通知的应答时间（5s），超时应答或应答失败微信将判断为回调通知失败，在一定周期内会重复发送回调通知。

### Q：“商品券回调通知”中返回手机号的功能，要如何开通？

A：当前手机号发券功能仅开放给少量商户试行，若有相关需求可以先联系对应的微信支付行业运营进行评估。

### Q：如果给多个服务商商户号/品牌id配置了同一个商品券回调地址，接收到回调时要如何区分本次回调属于哪个服务商商户号/品牌id？

A：回调的请求头中会携带验签所需的【微信支付平台证书序列号/微信支付公钥ID】 `Wechatpay-Serial`，每个服务商商户号/品牌id都有唯一的证书序列号/公钥ID，可以以此作为判断条件，但建议为不同的服务商商户号/品牌id配置不同的回调通知地址。

### Q：不同业务设置了同一个回调通知地址，如何判断当前回调通知为商品券的领券回调通知？

A：回调通知会返回【通知类型】 `event_type` 字段，不同业务不同环节返回的类型不同，商品券领券通知的返回值为“PRODUCT\_COUPON\_SP.SEND”。

### Q：通过不同渠道发放商品券都会有“商品券回调通知”吗？

A：都会有，回调通知的内容会包含【发券渠道】 `send_channel` 参数信息。

## 五、商品券核销

### Q：调用“核销用户商品券”接口报错：用户券状态非法

A：发券完成后，还需要调用“确认发放用户商品券”接口进行确认，只有在【用户商品券状态】为已生效时（ `"coupon_state" : "EFFECTIVE"`），才能进行核销。

商户侧可通过调用“查询用户商品券详情（[品牌模式](https://pay.weixin.qq.com/doc/brand/4015736414.md)/[服务商模式](https://pay.weixin.qq.com/doc/v3/partner/4015781582.md)）”接口确认【用户商品券状态】 `coupon_state`。

### Q：调用“核销用户商品券”接口报错：券不存在

A：该报错是由于未查询到该用户有对应code的商品券，建议检查以下几点：

1、openid是否正确

2、券code是否正确

3、要核销的券是否为“商品券”，本接口只能核销“商品券”，其他业务（商家券、代金券等）的券code无法查询到并核销

### Q：商品券核销组件的弹框支持展示多张券吗？

A：支持。

### Q：调用“核销用户商品券”接口报错：券已被删除

A：用户主动删除了领取的商品券，已删除的券无法被核销。

### Q：调用“核销用户商品券”接口报错：已使用过此单号核销券

A：“此单号”指【核销请求单号】 `out_request_no`，每次调用核销接口使用的请求单号都需更换，保持唯一性。

## 六、失效与退券

### Q：调用“退券”接口后，商品券会退回到用户摇优惠的卡包吗？

A：只有在用户商品券的有效期内进行退券，才会退回用户摇优惠的卡包，并可再次使用。

### Q：调用“退券”接口报错：券当前是可用的

A：未核销的券不支持调用“退券”接口

## 七、品牌经营平台

### Q：商品券是否可以在品牌经营平台上进行操作管理？例如添加批次、修改商品券信息等

A：不支持，商品券只能通过调用接口的形式进行管理，品牌经营平台只能查看商品券信息。

## 八、用户客户端

### Q：商家名片的客户端页面只有“服务”分页，没有“优惠”分页的原因是什么？

A：只有银行品牌会有“优惠”分页，用户在摇优惠领取的券在【摇优惠-我的】页面会直接展示“我的优惠”。

### Q：从摇优惠跳转到商户的小程序，对应的场景值是什么？

A：按小程序跳转小程序返回场景值：1037

### Q：已为批次关联品牌门店，但用户领券后，客户端页面没有展示门店信息是为什么？

A：请检查批次关联的门店id是否为生效中的门店，只有生效的门店会展示

### Q：核销商品券后，用户客户端为什么没有收到已使用券的消息通知？

A：给客户端发送用券消息的需满足以下条件：

1、需要在交易完成的3分钟内调用核销接口

2、在核销时传了订单信息（【关联微信支付订单信息】 `associated_order_info` 或【关联微信支付分订单信息】 `associated_pay_score_order_info`），且该笔订单真实存在。

### Q：商品券（多次优惠）用户已使用多张券，申请第一笔订单的退款后，客户端优惠详情页面显示的已使用的次数进度条是否会回退？

A：不会，券已发放，不会因为之前使用券的订单发生退款而收回后续已使用的券，因此客户端显示的进度条不会回退。

## 九、手机号发券（该功能目前仅开放少量商户试行）

### Q：如何识别什么渠道来源的发券事件需要更新为按手机号发券

A：识别「摇一摇有优惠」发放渠道，phone\_number 字段非空，说明用户被灰度到，需要更新为按手机号发券

### Q：用户手机号信息存储在什么字段，如何解密该字段

A：见[领券事件回调通知](https://pay.weixin.qq.com/doc/brand/4015755761.md)的phone\_number即为明文的【领券手机号】字段，按照 APIv3接口解密，可参考[如何解密回调报文](https://pay.weixin.qq.com/doc/brand/4015407591.md)

### Q：商家如何根据用户手机号发券【重点】

A：商家自有逻辑，在摇一摇渠道，按照以下优先级发放商品券

- 优先按领券事件返回的用户指定手机号发券

  - 微信回传的“openid - 手机号”与商家侧“openid - 手机号”一致：发券

  - 微信回传的“openid - 手机号”与商家侧“openid - 手机号”不一致：不发券，资格挂起，待用户绑定至准确手机号后下发
- 当手机号未注册时，资格挂在手机号待用户注册后发放或代用户注册新账号并直接发放

- 当领券事件未带手机号时（存在极少数情况）兜底用微信openid发券


请仔细阅读手机号发券规则（见下文档）

[指定手机号发券账号矩阵](https://doc.weixin.qq.com/sheet/e3_AJUAqAYGADA3gq6qPgxQpGEgoyX72?scode=AJEAIQdfAAoHZVPqFIAJUAqAYGADA&tab=BB08J2)

![](https://gtimg.wechatpay.cn/resource/xres/mmpaydoc/static/img/5b75d3b2523a0a2c2422a26749c2dec8.png)

![](https://gtimg.wechatpay.cn/resource/xres/mmpaydoc/static/img/5b75d3b2523a0a2c2422a26749c2dec8.png)