常见问题
更新时间：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: 线下滴码核销”
更多投放计划字段详情可参考：投放计划配置指引-字段介绍
Q：商品券各个字段在客户端的展示效果是怎样的？
A：可参考产品示例图（单券）和产品示例图（多次优惠）
Q：创建商品券设置【券可核销时间】coupon_available_period 时，设置了多种可核销的时间段，券的实际可核销时间会如何取值？
A：会取各时间段的“交集”时间，具体可参考文档：商品券可核销时间规则说明
Q：调用“创建商品券”接口报错：appid非法
A：请检查appid是否为品牌/服务商关联的appid。
品牌关联appid：
可选择以下两种路径之一进行关联，关联的前提为已通过微信认证的appid：
路径一：小程序、服务号、公众号、APP类型的都可以按以下步骤进行关联：
步骤1：品牌方在【品牌经营平台-账号管理-下单appid管理】页面，点击“关联appid”。
步骤2：品牌经营平台完成关联后，将在次日生效，请耐心等待。
路径二：小程序、APP类型的appid，如果是用于支付交易的appid，可通过“交易连接名片”功能进行关联，两种关联方式：
方式一：服务商通过商家名片下的“交易连接名片”功能，为品牌方关联appid。（目前只支持服务商模式）
方式二：品牌方在【品牌经营平台-商家名片-交易链接名片】页面，点击“添加”关联appid。
服务商关联appid（目前只支持服务商模式）：
服务商可登录服务商平台，通过路径【产品中心 -> APPID账号管理 -> 我关联的APPID账号】来查看所有绑定的APPID账号。
在该页面可以新增关联appid，具体流程请参考服务商商户号与AppID账号关联管理。
Q：调用“创建商品券”接口报错：appid不存在
A：appid本身的值是否正确，例如：不能填写不存在的appid；检查传的值是否带有空格之类不属于appid的特殊符号等。
Q：创建商品券时，设置的【券生效后N天内可用】available_days和【领券后需等待N天才生效】wait_days_after_receive，其中的天数是按自然日计算的，还是24小时计算的？
A：按自然日计算。例如：
“1天内可用”，就是发放当天可用，过了凌晨12点未使用，券就会过期；
“1天后才生效”，就是发放后，当天过了凌晨12点，券就会开始生效。
Q：商品券在什么场景下适合使用预上传Code的【券Code分配模式】coupon_code_mode？
A：商户侧已有一套券code（券码）核销系统，微信生成自动生成的券码无法识别，需要使用自己系统生成的code才能识别时，适合使用该模式。
Q：商品券（多次优惠）的批次组中，各个批次的商品券类型可以设置为不同的吗？例如第一次用满减券，第二次、第三次用折扣券。
A：不支持一个批次组内有不同商品券类型的批次，【商品券类型】type是在创券时设置在"商品券"维度的信息，不是"批次组/批次"维度单独设置的信息，因此所有批次的类型都是统一的。
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：调用“修改商品券批次(组)发放预算”接口减少【目标批次发放次数总上限】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：不支持，批次组中各个批次的有效期都是统一的。
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的会员，在商家名片的页面查看券时，券会显示一个“会员”的标签。不传则不显示“会员”的标签，示例图如下：
Q：商品券发券组件的弹框支持展示多张券吗？
A：不支持
Q：发放商品券时是否可以同时发多张券？
A：不支持同时发多张券，一次只能发一张。
Q：使用相同的参数调用“向用户预发放商品券”接口，返回的token是否相同？是否会进行幂等处理？
A：每次调用接口都会返回不同的token，每个token的有效期为5分钟，过期后需要重新调用接口获取。
Q：发放商品券时，是否会校验重复发券？校验的规则是怎样的？
A：接口会根据用户(unionid)+stock_id+send_request_no校验是否发放的为同一张券。
注意：一个微信账号只会有一个unionid，同一微信账号在不同的appid下会有不同的openid，如果不同的appid+openid指向的是同一个unionid，即为同一用户领券。
四、商品券回调通知
Q：商品券事件通知地址是否可以在平台上手动配置？
A：不可以，只能通过“设置商品券事件通知地址（品牌模式/服务商模式）”接口进行配置。
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列表可查看：回调处理逻辑注意事项；
商品券回调通知IP白名单 | ||
|---|---|---|
81.71.199.64 | 81.71.198.25 | 81.71.199.59 |
服务器开启了 CC 攻击防护、WAF（Web 应用防火墙）等安全策略，误将微信支付的回调请求判定为恶意请求并拦截。
2.2、网络链路故障
商户服务器所在网络存在链路丢包、延迟过高（如超过 3 秒），导致微信支付发送的通知请求超时；
商户使用的 CDN 或反向代理（如 Nginx、Cloudflare）配置异常，未将回调请求正确转发至后端业务服务器。
3、其他场景
如果商户没有设置apiv3key微信支付不会发送回调通知。
调用“创建商品券/添加商品券批次(组)”接口时设置的【事件通知AppID】
notify_appid是否正确。如果同一个回调地址有些回调能收到，有些回调收不到，请确认下该回调地址是否有多个服务器配置，是否只有某部分机器能收到，另一部分的机器无法收到，再排查未接收到回调的服务器是否正常。
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"），才能进行核销。
商户侧可通过调用“查询用户商品券详情（品牌模式/服务商模式）”接口确认【用户商品券状态】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：只有银行品牌会有“优惠”分页，用户在摇优惠领取的券在【摇优惠-我的】页面会直接展示“我的优惠”。
Q：从摇优惠跳转到商户的小程序，对应的场景值是什么？
A：按小程序跳转小程序返回场景值：1037
Q：已为批次关联品牌门店，但用户领券后，客户端页面没有展示门店信息是为什么？
A：请检查批次关联的门店id是否为生效中的门店，只有生效的门店会展示
Q：核销商品券后，用户客户端为什么没有收到已使用券的消息通知？
A：给客户端发送用券消息的需满足以下条件：
1、需要在交易完成的3分钟内调用核销接口
2、在核销时传了订单信息（【关联微信支付订单信息】associated_order_info或【关联微信支付分订单信息】associated_pay_score_order_info），且该笔订单真实存在。
