创建商品券

更新时间:2025.12.31
||| 安装 Skill

品牌方可以通过该接口为品牌创建商品券和批次组。微信支付创建成功后,会返回此次创建的商品券、批次组。品牌方可在【经营平台】上配置【活动】对商品券进行投放。

前置条件:品牌方已【设置商品券事件通知地址】

接口说明

支持商户:【品牌商户】

请求方式:【POST】/brand/marketing/product-coupon/product-coupons

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

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

接口限频:20/秒(品牌ID维度)

请求参数
折叠全部参数

Header  HTTP头参数

 Authorization  必填 string

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


 Accept  必填 string

请设置为application/json


 Content-Type  必填 string

请设置为application/json


 Wechatpay-Serial  必填 string

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


body  包体参数

out_request_no  必填   string(40)

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


 scope  必填   string

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

可选取值

  • ALL:  全场商品可用券,此时券类型 type 仅可配置为 NORMAL 或 DISCOUNT

  • SINGLE:  部分商品可用券,此时券类型 type 配置不受限制,即可配置为 NORMAL、DISCOUNT 或 EXCHANGE

  • CATEGORY:  品类券。适用于商户对某一品类商品提供优惠的场景;系统侧不维护商品/品类清单,具体可用商品范围由商户在 display_info 描述、图片等字段中向用户告知,并在核销时由商户自行判定。此时券类型 type 仅可配置为 NORMAL 或 DISCOUNT


 type  必填   string

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

可选取值

  • NORMAL:  满减券

  • DISCOUNT:  折扣券

  • EXCHANGE:  兑换券,仅在 scope 为 SINGLE 时可配置


 usage_mode  必填   string

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

  • PROGRESSIVE_BUNDLE:  多次优惠,由一组批次组成,每阶梯次序对应一个批次。用户按顺序使用,每次核销后发放下一张券,直到用完为止


 progressive_bundle_usage_info  必填   object

【多次优惠模式信息】 多次优惠模式配置信息,当且仅当 usage_mode 为 PROGRESSIVE_BUNDLE 时必传,其他模式不应填写。

属性

 count  必填   integer

【可使用次数】 多次优惠领取后用户可使用次数,最少3次,最多15次


 interval_days  选填   integer

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

  • 间隔 0 天表示不限制,使用后当天仍然可以继续使用下一次优惠

  • 间隔 1 天表示使用后当天不再可用,下一次优惠需要等到次日 00:00:00 才能使用

  • 间隔 2 天表示使用后当天和次日不再可用,下一次优惠需要等到第三天 00:00:00 才能使用

  • 依此类推……

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


 display_info  必填   object

【展示信息】 商品券展示信息,展示结果可参考商品券示意图(多次优惠模式)

属性

 name  必填   string(25)

【商品券名称】 商品券名称,长度为3-25个UTF-8字符


 image_url  必填   string

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

  • 请参考商品券图片设计规范进行设计

  • 要求图片宽高比1:1,建议尺寸1080*1080

  • 大小不超过2M

  • 建议图片格式:透明PNG格式

  • 需要注意保留透明边距(上下左右各120px)


 background_url  必填   string

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

  • 要求图片宽高比65:77,建议尺寸1170*1326

  • 大小不超过2M

  • 建议图片格式:JPG/PNG格式

  • 需要注意保留「商品名称」与「商品图」的安全区域


 detail_image_url_list  选填   array[string]

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

  • 要求图片宽高比65:77,建议尺寸1170*1326

  • 大小不超过2M

  • 建议图片格式:JPG/PNG格式


 original_price  选填   integer

【商品原价】 单位为分,用于对外展示,默认为 0,最大为 10000000。不填写时默认为 0


 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个单品,且不能少于设置的pick_count数量

属性

 name  必填   string(15)

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


 price  必填   integer

【单品价格】 单位为分,必须大于0。


 count  必填   integer

【单品数量】 最多99个


 image_url  选填   string

【单品图片】 单品图片URL地址,仅支持通过【图片上传API】获取的图片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(40)

【外部商品ID】 品牌侧的商品标识,品牌可自行选择传入,长度不超过40个字符。

注:微信支付不校验此参数的唯一性,即允许多个商品券共享外部商品ID。


 stock_bundle  必填   object

【批次组】 商品券批次组信息,当且仅当 usage_mode 为 PROGRESSIVE_BUNDLE 时必传,其他模式不应填写。

属性

 remark  选填   string(20)

【备注】 仅配置品牌方可见,用于自定义信息,最多20个UTF-8字符


 coupon_code_mode  必填   string

【券Code分配模式】 决定发券时用户商品券Code如何产生,批次组内每一个批次都会设置为此值

可选取值

  • WECHATPAY:  微信支付随机生成,发券时由微信支付系统自动随机生成券码,品牌方无需干预,微信支付随机生成的券Code长度限制为40个字符以内

  • UPLOAD:  品牌方预上传Code,品牌方需先使用【预上传券Code API(多次优惠)】上传自定义Code,微信支付系统发券时从中随机选取,当预存Code不足时可能影响发券,品牌应及时补充


 stock_send_rule  必填   object

【批次组发放规则】 批次组内的批次会继承此规则

属性

 max_count  必填   integer

【批次组发放次数总上限】 批次组在生命周期内总发放次数,最多 100,000,000 次。批次组内的所有批次会继承此上限。


 max_count_per_day  选填   integer

【批次组每日发放次数上限】 批次组在每天内发放次数上限,每日刷新,最多 100,000,000 次。默认不限制每日发放上限。

注:为保证用户领取/使用多次优惠的体验,批次组内的首个批次会继承此上限,但其余批次会保持为不限制。


 max_count_per_user  必填   integer

【每个用户领取批次组次数上限】 每个用户最多可领取本批次组的次数,最多 100 次。批次组内的所有批次会继承此上限。


 progressive_bundle_usage_rule  必填   object

【多次优惠批次组使用规则】 包含组合内部每一个批次的优惠规则,会根据内部的优惠规则列表依次创建批次放入批次组,当且仅当 usage_mode 为 PROGRESSIVE_BUNDLE 时必填。

多次优惠的批次组下各轮次,需要保证每一轮次 “优惠力度”大于等于前一轮次。但是首轮除外,即首轮的“优惠力度”可以小于/大于/等于其他任意轮次。
具体定义:

  • 当满减券时:各轮次中“减免金额”数值,每轮次需大于等于前一轮次,首轮除外

  • 当折扣券时:各轮次中“减免百分比”数值,每轮次需大于等于前一轮次,首轮除外

  • 当兑换券时:各轮次中“兑换价”数值,每轮次需小于等于前一轮次,首轮除外

举例:考虑一组折扣券5次优惠

  • 8折、7折、6折、5折、4折:允许

  • 8折、8折、8折、8折、8折:允许

  • 6折、7折、6折、5折、4折:允许

  • 6折、7折、7折、7折、7折:允许

  • 6折、7折、8折、7折、7折:不允许,因为第三轮的“优惠力度”小于第二轮

  • 8折、7折、6折、7折、4折:不允许,因为第四轮的“优惠力度”小于第三轮

属性

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

距离当前创建批次的时间不能超过90天,批次有效期最长不超过366天,摇优惠场景建议设置批次时间大于等于5天


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

批次有效期最长不超过366天


 available_days  选填   integer

【券生效后N天内可用】 日期区间内,券生效后 N 天内有效,最多365天。例如:

  • 生效当天内有效填 1

  • 生效后2天内有效填 2

  • 依此类推……

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

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

注:不可与 irregular_available_period_list 同时配置


 wait_days_after_receive  选填   integer

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

  • 领券后当天开始生效则无需填写

  • 领券后第二天开始生效则填写 1

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

需配合 available_days 一同填写,不可单独填写。

注:不可与 irregular_available_period_list 同时配置


 weekly_available_period  选填   object

【每周固定可用时间】 日期区间内,每周固定时间可以使用。可与 available_days 和 wait_days_after_receive 一同配置,一同配置时条件需同时满足券才可用(时间范围取交集)。

注:不可与 irregular_available_period_list 同时配置

属性

 day_list  必填   array[string]

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

可选取值

  • MONDAY:  周一可用

  • TUESDAY:  周二可用

  • WEDNESDAY:  周三可用

  • THURSDAY:  周四可用

  • FRIDAY:  周五可用

  • SATURDAY:  周六可用

  • SUNDAY:  周日可用


 day_period_list  选填   array[object]

【当天可用时间段】 生效当天特定时间段内有效,可以配置多个时间段。最多可以配置 3 个时间段。不配置则全天可用。

属性

 begin_time  必填   integer

【当天可用开始时间】 当天可用时间距离当天 00:00:00 的秒数,如 60 表示当天 00:01:00 开始可用。取值范围 [0,86399] 且必须小于 end_time


 end_time  必填   integer

【当天可用结束时间】 当天结束可用时间距离当天 00:00:00 的秒数,如 86399 表示当天 23:59:59 结束可用。取值范围 [0,86399] 且必须大于 begin_time


 irregular_available_period_list  选填   array[object]

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

注:不可与 available_days、wait_days_after_receive、weekly_available_period 同时配置

属性

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


 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_seconds  选填 integer

【领取后N秒内有效】 日期区间内,用户领券后立即生效,自领取时刻起 N 秒内可用,不与自然日对齐。取值范围为 3600~86400,且仅支持 3600 的整数倍。

注:不可与 available_days、wait_days_after_receive、weekly_available_period、irregular_available_period_list 同时配置


 normal_coupon_list  选填   array[object]

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

属性

 threshold  必填   integer

【门槛金额】 使用门槛金额,单位为分,达到该门槛后可享受满减优惠。门槛可以为0,即无门槛。例如:

  • 满 100 元可用填 10000

  • 满 0.01 元可用填 1


 discount_amount  必填   integer

【固定减免金额】 固定减免金额,单位为分,必须大于0。


 discount_coupon_list  选填   array[object]

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

属性

 threshold  必填   integer

【门槛金额】 使用门槛金额,单位为分,达到该门槛后可享受折扣优惠。门槛可以为0,即无门槛。例如:

  • 满 100 元可用填 10000

  • 满 0.01 元可用填 1


 percent_off  必填   integer

【固定减免百分比】 表示减免金额为总金额的百分比,必须大于0。例如:填入 30 表示减免 30%,即打 7 折


 exchange_coupon_list  选填   array[object]

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

属性

 threshold  必填   integer

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

  • 满 100 元可用填 10000

  • 满 0.01 元可用填 1


 exchange_price  必填   integer

【固定兑换价格】 单位为分,必须大于或等于0。


 usage_rule_display_info  必填   object

【券使用规则展示信息】 券使用规则展示信息,批次组内每一个批次都会设置为此值

属性

 coupon_usage_method_list  必填   array[string]

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

可选取值

  • OFFLINE:  线下滴码核销,点击券“立即使用”跳转展示券二维码详情(投放计划暂不支持此核销方式)

  • MINI_PROGRAM:  线上小程序核销,点击券“立即使用”跳转至配置的商家小程序(需要添加小程序AppID和Path)

  • APP:  APP核销,在商家APP内核销

  • PAYMENT_CODE:  微信支付付款码核销,用户点击券“立即使用”将跳转至微信支付钱包付款码,品牌方扫描付款码后可通过付款码获取到用户openid,通过openid查询并核销用户券,核销后再发起下单,适合线下支付场景


 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的H5跳转路径】 品牌方APP的H5跳转路径。在 app_jump_type 为 H5 时必填。


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


 app_jump_type  选填   string

【APP跳转类型】 APP跳转类型,在 coupon_usage_method_list 中包含 APP 时必填。

可选取值

  • H5:  跳转H5,点击券立即使用跳转至配置的H5页面

  • PASSCODE_LINK:  口令链接,点击券立即使用展示口令链接供用户复制使用

  • USAGE_GUIDE: 展示使用指引,引导前往APP核销


 passcode_link  选填   string

【口令链接】 口令链接。在 app_jump_type 为 PASSCODE_LINK 时必填。


 coupon_display_info  必填   object

【用户商品券展示信息】 用户商品券在卡包中的展示详情,包括引导用户的自定义入口,批次组内每一个批次都会设置为此值

属性

 code_display_mode  必填   string

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

可选取值

  • INVISIBLE:  不展示Code

  • BARCODE:  条形码

  • QRCODE:  二维码


 background_color  选填   string

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


 entrance_mini_program  选填   object

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

属性

 appid  必填   string

【小程序AppID】 品牌方小程序的AppID,可在微信公众平台查看,该小程序与品牌存在绑定关系


 path  必填   string

【小程序跳转路径】 品牌方小程序内部跳转路径


 entrance_wording  必填   string(5)

【入口文案】 小程序入口文案,长度不超过5个UTF-8字符


 guidance_wording  必填   string(6)

【引导文案】 小程序入口引导文案,长度不超过6个UTF-8字符


 entrance_official_account  选填   object

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

属性

 appid  必填   string

【公众号AppID】 微信公众号唯一标识,可在微信公众平台查看,该公众号应与品牌方存在绑定关系

 

 notify_config  必填   object

【事件通知配置】 发生券相关事件时,微信支付会向品牌方发送通知,需要提供通知相关配置,批次组内每一个批次都会设置为此值

属性

 notify_appid  必填   string

【事件通知AppID】 品牌的AppID,支持小程序、服务号、公众号、APP类型的AppID,可在微信公众平台查看,用于券事件通知时计算用户的OpenID,需要与品牌存在绑定关系


 store_scope  必填   string

【可用门店范围】 控制该批次可以在品牌下哪些门店使用,批次组内每一个批次都会设置为此值

可选取值

  • NONE:  无关联门店,该批次对外不展示可用门店信息

  • ALL:  所有门店可用,该批次在品牌下的所有门店可用,品牌无需为该批次关联门店列表

  • SPECIFIC:  特定门店可用,品牌需调用关联门店接口关联门店,关联后该批次在关联的门店可用


 show_as_exchange  选填   boolean

【是否展示兑换价】 是否按兑换价展示商品券。true 表示 C 端以「商品原价 − 满减金额」展示兑换价,而非满减金额。仅单品满减券且品牌在换价白名单内可开启;不传默认为 false。创建后不可修改。


 available_product_no_list  选填   array[string(20)]

【可用商品编码列表】 本券允许核销的商品编码,商户可自行选择传入,最多100个,可使用数字、大小写字母组成,长度不超过20个字符。仅优惠范围为单品或品类时可填写,全场不可填写

 

 

请求示例

curl
Java
Go

POST

创建全场折扣多次优惠券

1curl -X POST \
2  https://api.mch.weixin.qq.com/brand/marketing/product-coupon/product-coupons \
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    "stock_bundle" : {
9      "remark" : "8月工作日有效批次",
10      "coupon_code_mode" : "UPLOAD",
11      "stock_send_rule" : {
12        "max_count" : 10000000,
13        "max_count_per_user" : 1
14      },
15      "progressive_bundle_usage_rule" : {
16        "coupon_available_period" : {
17          "available_begin_time" : "2025-08-01T00:00:00+08:00",
18          "available_end_time" : "2025-08-31T23:59:59+08:00",
19          "available_days" : 30,
20          "weekly_available_period" : {
21            "day_list" : [
22              "MONDAY",
23              "TUESDAY",
24              "WEDNESDAY",
25              "THURSDAY",
26              "FRIDAY"
27            ]
28          }
29        },
30        "discount_coupon_list" : [
31          {
32            "threshold" : 10000,
33            "percent_off" : 50
34          },
35          {
36            "threshold" : 10000,
37            "percent_off" : 20
38          },
39          {
40            "threshold" : 10000,
41            "percent_off" : 30
42          }
43        ]
44      },
45      "usage_rule_display_info" : {
46        "coupon_usage_method_list" : [
47          "OFFLINE",
48          "MINI_PROGRAM",
49          "PAYMENT_CODE"
50        ],
51        "mini_program_appid" : "wx1234567890",
52        "mini_program_path" : "/pages/index/product",
53        "usage_description" : "工作日可用",
54        "coupon_available_store_info" : {
55          "description" : "所有门店可用,可使用小程序查看门店列表",
56          "mini_program_appid" : "wx1234567890",
57          "mini_program_path" : "/pages/index/store-list"
58        }
59      },
60      "coupon_display_info" : {
61        "code_display_mode" : "QRCODE",
62        "background_color" : "Color010",
63        "entrance_mini_program" : {
64          "appid" : "wx1234567890",
65          "path" : "/pages/index/product",
66          "entrance_wording" : "欢迎选购",
67          "guidance_wording" : "获取更多优惠"
68        },
69        "entrance_official_account" : {
70          "appid" : "wx1234567890"
71        }
72      },
73      "store_scope" : "NONE",
74      "notify_config" : {
75        "notify_appid" : "wx4fd12345678"
76      }
77    },
78    "out_product_no" : "Product_1234567890",
79    "scope" : "ALL",
80    "usage_mode" : "PROGRESSIVE_BUNDLE",
81    "display_info" : {
82      "name" : "全场多次折扣券",
83      "image_url" : "https://wxpaylogo.qpic.cn/wxpaylogo/xxxxx/xxx",
84      "background_url" : "https://wxpaylogo.qpic.cn/wxpaylogo/xxxxx/xxx",
85      "detail_image_url_list" : [
86        "https://wxpaylogo.qpic.cn/wxpaylogo/xxxxx/xxx"
87      ]
88    },
89    "type" : "DISCOUNT",
90    "out_request_no" : "12345_20250101_A3489",
91    "progressive_bundle_usage_info" : {
92      "count" : 3,
93      "interval_days" : 1
94    }
95  }'
96

应答参数
折叠全部参数

200 OK

 product_coupon_id  必填   string(40)

【商品券ID】 商品券的唯一标识,本接口成功时由微信支付生成


 scope  必填   string

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

可选取值

  • ALL:  全场商品可用券,此时券类型 type 仅可配置为 NORMAL 或 DISCOUNT

  • SINGLE:  部分商品可用券,此时券类型 type 配置不受限制,即可配置为 NORMAL、DISCOUNT 或 EXCHANGE

  • CATEGORY:  品类券。适用于商户对某一品类商品提供优惠的场景;系统侧不维护商品/品类清单,具体可用商品范围由商户在 display_info 描述、图片等字段中向用户告知,并在核销时由商户自行判定。此时券类型 type 仅可配置为 NORMAL 或 DISCOUNT


 type  必填   string

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

可选取值

  • NORMAL:  满减券

  • DISCOUNT:  折扣券

  • EXCHANGE:  兑换券,仅在 scope 为 SINGLE 时可配置


 usage_mode  必填   string

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

  • PROGRESSIVE_BUNDLE:  多次优惠,由一组批次组成,每阶梯次序对应一个批次。用户按顺序使用,每次核销后发放下一张券,直到用完为止


 progressive_bundle_usage_info  必填   object

【多次优惠模式信息】 多次优惠模式配置信息

属性

 count  必填   integer

【可使用次数】 多次优惠领取后用户可使用次数,最少3次,最多15次


 interval_days  选填   integer

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

  • 间隔 0 天表示不限制,使用后当天仍然可以继续使用下一次优惠

  • 间隔 1 天表示使用后当天不再可用,下一次优惠需要等到次日 00:00:00 才能使用

  • 间隔 2 天表示使用后当天和次日不再可用,下一次优惠需要等到第三天 00:00:00 才能使用

  • 依此类推……

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


 display_info  必填   object

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

属性

 name  必填   string(25)

【商品券名称】 商品券名称,长度为3-25个UTF-8字符


 image_url  必填   string

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

  • 请参考商品券图片设计规范进行设计

  • 要求图片宽高比1:1,建议尺寸1080*1080

  • 大小不超过2M

  • 建议图片格式:透明PNG格式

  • 需要注意保留透明边距(上下左右各120px)


 background_url  必填   string

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

  • 要求图片宽高比65:77,建议尺寸1170*1326

  • 大小不超过2M

  • 建议图片格式:JPG/PNG格式

  • 需要注意保留「商品名称」与「商品图」的安全区域


 detail_image_url_list  选填   array[string]

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

  • 要求图片宽高比65:77,建议尺寸1170*1326

  • 大小不超过2M

  • 建议图片格式:JPG/PNG格式


 original_price  选填   integer

【商品原价】 单位为分,用于对外展示,默认为 0,最大为 10000000。不填写时默认为 0


 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个单品,且不能少于设置的pick_count数量

属性

 name  必填   string(15)

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


 price  必填   integer

【单品价格】 单位为分,必须大于0。


 count  必填   integer

【单品数量】 最多99个


 image_url  选填   string

【单品图片】 单品图片URL地址,仅支持通过【图片上传API】获取的图片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:  已失效,品牌方主动调用失效接口使商品券失效


 stock_bundle  必填   object

【批次组】 商品券批次组信息

属性

 stock_bundle_id  必填   string(40)

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


 stock_list  必填   array[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不足时可能影响发券,品牌应及时补充


 coupon_code_count_info  选填   object

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

属性

 total_count  必填   integer

【已上传的Code总数】 品牌方为此批次已经上传过的券Code总数量


 available_count  必填   integer

【当前可用的Code数】 品牌方为此批次已经上传过的券Code中,当前剩余可用的券Code数量


 stock_send_rule  必填   object

【发放规则】 发放规则

属性

 max_count  必填   integer

【发放次数总上限】 批次在生命周期内总发放次数,最多 100,000,000 次


 max_count_per_day  选填   integer

【每日发放次数上限】 批次在每天内发放次数上限,每日刷新,最多 100,000,000 次。默认不限制每日发放上限


 max_count_per_user  必填   integer

【每个用户领取次数上限】 每个用户最多可领取本批次的次数,最多 100 次。


 progressive_bundle_usage_rule  必填   object

【多次优惠使用规则】 本批次属于某个多次优惠批次组,这里记录的是本批次的使用规则,当且仅当 usage_mode 为 PROGRESSIVE_BUNDLE 时提供,其他场景不提供

属性

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

距离当前创建批次的时间不能超过90天,批次有效期最长不超过366天,摇优惠场景建议设置批次时间大于等于5天


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

批次有效期最长不超过366天


 available_days  选填   integer

【券生效后N天内可用】 日期区间内,券生效后 N 天内有效,最多365天。例如:

  • 生效当天内有效填 1

  • 生效后2天内有效填 2

  • 依此类推……

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

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

注:不可与 irregular_available_period_list 同时配置


 wait_days_after_receive  选填   integer

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

  • 领券后当天开始生效则无需填写

  • 领券后第二天开始生效则填写 1

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

需配合 available_days 一同填写,不可单独填写。

注:不可与 irregular_available_period_list 同时配置


 weekly_available_period  选填   object

【每周固定可用时间】 日期区间内,每周固定时间可以使用。可与 available_days 和 wait_days_after_receive 一同配置,一同配置时条件需同时满足券才可用(时间范围取交集)。

注:不可与 irregular_available_period_list 同时配置

属性

 day_list  必填   array[string]

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

可选取值

  • MONDAY:  周一可用

  • TUESDAY:  周二可用

  • WEDNESDAY:  周三可用

  • THURSDAY:  周四可用

  • FRIDAY:  周五可用

  • SATURDAY:  周六可用

  • SUNDAY:  周日可用


 day_period_list  选填   array[object]

【当天可用时间段】 生效当天特定时间段内有效,可以配置多个时间段。最多可以配置 3 个时间段。不配置则全天可用。

属性

 begin_time  必填   integer

【当天可用开始时间】 当天可用时间距离当天 00:00:00 的秒数,如 60 表示当天 00:01:00 开始可用。取值范围 [0,86399] 且必须小于 end_time


 end_time  必填   integer

【当天可用结束时间】 当天结束可用时间距离当天 00:00:00 的秒数,如 86399 表示当天 23:59:59 结束可用。取值范围 [0,86399] 且必须大于 begin_time


 irregular_available_period_list  选填   array[object]

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

注:不可与 available_days、wait_days_after_receive、weekly_available_period 同时配置

属性

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


 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_seconds  选填 integer

【领取后N秒内有效】 日期区间内,用户领券后立即生效,自领取时刻起 N 秒内可用,不与自然日对齐。取值范围为 3600~86400,且仅支持 3600 的整数倍。

注:不可与 available_days、wait_days_after_receive、weekly_available_period、irregular_available_period_list 同时配置


 normal_coupon  选填   object

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

属性

 threshold  必填   integer

【门槛金额】 使用门槛金额,单位为分,达到该门槛后可享受满减优惠。门槛可以为0,即无门槛。例如:

  • 满 100 元可用填 10000

  • 满 0.01 元可用填 1


 discount_amount  必填   integer

【固定减免金额】 固定减免金额,单位为分,必须大于0。


 discount_coupon  选填   object

【折扣券使用规则】  type 为 DISCOUNT 时必填,其他类型不应填写`

属性

 threshold  必填   integer

【门槛金额】 使用门槛金额,单位为分,达到该门槛后可享受折扣优惠。门槛可以为0,即无门槛。例如:

  • 满 100 元可用填 10000

  • 满 0.01 元可用填 1


 percent_off  必填   integer

【固定减免百分比】 表示减免金额为总金额的百分比,必须大于0。例如:填入 30 表示减免 30%,即打 7 折


 exchange_coupon  选填   object

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

属性

 threshold  必填   integer

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

  • 满 100 元可用填 10000

  • 满 0.01 元可用填 1


 exchange_price  必填   integer

【固定兑换价格】 单位为分,必须大于或等于0。


 stock_bundle_info  必填   object

【批次组信息】 批次所在批次组信息

属性

 stock_bundle_id  必填   string(40)

【批次所属批次组ID】 商品券批次组的唯一标识,【创建商品券(多次优惠)】或【添加商品券批次组】时由微信支付生成


 stock_bundle_index  必填   integer

【批次在批次组内的次序】 本批次在批次组内的次序,从0开始


 usage_rule_display_info  必填   object

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

属性

 coupon_usage_method_list  必填   array[string]

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

可选取值

  • OFFLINE:  线下滴码核销,点击券“立即使用”跳转展示券二维码详情(投放计划暂不支持此核销方式)

  • MINI_PROGRAM:  线上小程序核销,点击券“立即使用”跳转至配置的商家小程序(需要添加小程序AppID和Path)

  • APP:  APP核销,在商家APP内核销

  • PAYMENT_CODE:  微信支付付款码核销,用户点击券“立即使用”将跳转至微信支付钱包付款码,品牌方扫描付款码后可通过付款码获取到用户openid,通过openid查询并核销用户券,核销后再发起下单,适合线下支付场景


 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的H5跳转路径】 品牌方APP的H5跳转路径。在 app_jump_type 为 H5 时必填。


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


app_jump_type  选填   string

【APP跳转类型】 APP跳转类型,在 coupon_usage_method_list 中包含 APP 时必填。

可选取值

  • H5:  跳转H5,点击券立即使用跳转至配置的H5页面

  • PASSCODE_LINK:  口令链接,点击券立即使用展示口令链接供用户复制使用

  • USAGE_GUIDE: 展示使用指引,引导前往APP核销


 passcode_link  选填   string

【口令链接】 口令链接。在 app_jump_type 为 PASSCODE_LINK 时必填。


 coupon_display_info  必填   object

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

属性

 code_display_mode  必填   string

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

可选取值

  • INVISIBLE:  不展示Code

  • BARCODE:  条形码

  • QRCODE:  二维码


 background_color  选填   string

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


 entrance_mini_program  选填   object

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

属性

 appid  必填   string

【小程序AppID】 品牌方小程序的AppID,可在微信公众平台查看,该小程序与品牌存在绑定关系


 path  必填   string

【小程序跳转路径】 品牌方小程序内部跳转路径


 entrance_wording  必填   string(5)

【入口文案】 小程序入口文案,长度不超过5个UTF-8字符


 guidance_wording  必填   string(6)

【引导文案】 小程序入口引导文案,长度不超过6个UTF-8字符


 entrance_official_account  选填   object

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

属性

 appid  必填   string

【公众号AppID】 微信公众号唯一标识,可在微信公众平台查看,该公众号应与品牌方存在绑定关系


 notify_config  必填   object

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

属性

 notify_appid  必填   string

【事件通知AppID】 品牌的AppID,支持小程序、服务号、公众号、APP类型的AppID,可在微信公众平台查看,用于券事件通知时计算用户的OpenID,需要与品牌存在绑定关系


 store_scope  必填   string

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

可选取值

  • NONE:  无关联门店,该批次对外不展示可用门店信息

  • ALL:  所有门店可用,该批次在品牌下的所有门店可用,品牌无需为该批次关联门店列表

  • SPECIFIC:  特定门店可用,品牌需调用关联门店接口关联门店,关联后该批次在关联的门店可用


 sent_count_info  必填   object

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

属性

 total_count  必填   integer

【已发放总次数】 批次在生命周期内已发放次数


 today_count  必填   integer

【当天已发放次数】 批次在当天已发放次数


 state  必填   string

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

可选取值

  • AUDITING:  审批中

  • SENDING:  发放中

  • PAUSED:  已暂停

  • STOPPED:  已停止,当前已到达结束时间

  • DEACTIVATED:  已失效,品牌方主动调用失效接口使批次失效


 deactivate_request_no  选填   string(128)

【失效请求单号】  state 为 DEACTIVATED 时提供,返回品牌方调用【失效商品券批次API】时传入的请求流水号


 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(150)

【失效原因】  state 为 DEACTIVATED 时提供,返回品牌方调用【失效商品券批次API】时传入的失效原因


 show_as_exchange  选填   boolean

【是否展示兑换价】 是否按兑换价展示商品券。true 表示 C 端以「商品原价 − 满减金额」展示兑换价。仅当开关为 true 时返回本字段;为 false 或未设置时不返回,商户应按未开启(按满减金额展示)处理。


 available_product_no_list  选填   array[string]

【可用商品编码列表】 商户创建商品券时主动传入的可用商品编码,原样返回

应答示例

200 OK

创建全场折扣多次优惠券

1{
2  "product_coupon_id" : "1000000014",
3  "scope" : "ALL",
4  "type" : "DISCOUNT",
5  "usage_mode" : "PROGRESSIVE_BUNDLE",
6  "progressive_bundle_usage_info" : {
7    "count" : 3,
8    "interval_days" : 1
9  },
10  "display_info" : {
11    "name" : "全场满100立打8折",
12    "image_url" : "https://wxpaylogo.qpic.cn/wxpaylogo/xxxxx/xxx",
13    "background_url" : "https://wxpaylogo.qpic.cn/wxpaylogo/xxxxx/xxx",
14    "detail_image_url_list" : [
15      "https://wxpaylogo.qpic.cn/wxpaylogo/xxxxx/xxx"
16    ]
17  },
18  "state" : "EFFECTIVE",
19  "out_product_no" : "Product_1234567890",
20  "stock_bundle" : {
21    "stock_bundle_id" : "712315129419284901",
22    "stock_list" : [
23      {
24        "product_coupon_id" : "1000000014",
25        "stock_id" : "1000000014001",
26        "remark" : "8月工作日有效批次",
27        "coupon_code_mode" : "UPLOAD",
28        "coupon_code_count_info" : {
29          "total_count" : 0,
30          "available_count" : 0
31        },
32        "stock_send_rule" : {
33          "max_count" : 10000000,
34          "max_count_per_user" : 1
35        },
36        "progressive_bundle_usage_rule" : {
37          "coupon_available_period" : {
38            "available_begin_time" : "2025-08-01T00:00:00+08:00",
39            "available_end_time" : "2025-08-31T23:59:59+08:00",
40            "available_days" : 30,
41            "weekly_available_period" : {
42              "day_list" : [
43                "MONDAY",
44                "TUESDAY",
45                "WEDNESDAY",
46                "THURSDAY",
47                "FRIDAY"
48              ]
49            }
50          },
51          "discount_coupon" : {
52            "threshold" : 10000,
53            "percent_off" : 50
54          }
55        },
56        "stock_bundle_info" : {
57          "stock_bundle_id" : "712315129419284901",
58          "stock_bundle_index" : 0
59        },
60        "usage_rule_display_info" : {
61          "coupon_usage_method_list" : [
62            "OFFLINE",
63            "MINI_PROGRAM",
64            "PAYMENT_CODE"
65          ],
66          "mini_program_appid" : "wx1234567890",
67          "mini_program_path" : "/pages/index/product",
68          "usage_description" : "工作日可用",
69          "coupon_available_store_info" : {
70            "description" : "所有门店可用,可使用小程序查看门店列表",
71            "mini_program_appid" : "wx1234567890",
72            "mini_program_path" : "/pages/index/store-list"
73          }
74        },
75        "coupon_display_info" : {
76          "code_display_mode" : "QRCODE",
77          "background_color" : "Color010",
78          "entrance_mini_program" : {
79            "appid" : "wx1234567890",
80            "path" : "/pages/index/product",
81            "entrance_wording" : "欢迎选购",
82            "guidance_wording" : "获取更多优惠"
83          },
84          "entrance_official_account" : {
85            "appid" : "wx1234567890"
86          }
87        },
88        "notify_config" : {
89          "notify_appid" : "wx4fd12345678"
90        },
91        "store_scope" : "NONE",
92        "sent_count_info" : {
93          "total_count" : 0,
94          "today_count" : 0
95        },
96        "state" : "SENDING"
97      },
98      {
99        "product_coupon_id" : "1000000014",
100        "stock_id" : "1000000014002",
101        "remark" : "8月工作日有效批次",
102        "coupon_code_mode" : "UPLOAD",
103        "coupon_code_count_info" : {
104          "total_count" : 0,
105          "available_count" : 0
106        },
107        "stock_send_rule" : {
108          "max_count" : 10000000,
109          "max_count_per_user" : 1
110        },
111        "progressive_bundle_usage_rule" : {
112          "coupon_available_period" : {
113            "available_begin_time" : "2025-08-01T00:00:00+08:00",
114            "available_end_time" : "2025-08-31T23:59:59+08:00",
115            "available_days" : 30,
116            "weekly_available_period" : {
117              "day_list" : [
118                "MONDAY",
119                "TUESDAY",
120                "WEDNESDAY",
121                "THURSDAY",
122                "FRIDAY"
123              ]
124            }
125          },
126          "discount_coupon" : {
127            "threshold" : 10000,
128            "percent_off" : 20
129          }
130        },
131        "stock_bundle_info" : {
132          "stock_bundle_id" : "712315129419284901",
133          "stock_bundle_index" : 1
134        },
135        "usage_rule_display_info" : {
136          "coupon_usage_method_list" : [
137            "OFFLINE",
138            "MINI_PROGRAM",
139            "PAYMENT_CODE"
140          ],
141          "mini_program_appid" : "wx1234567890",
142          "mini_program_path" : "/pages/index/product",
143          "usage_description" : "工作日可用",
144          "coupon_available_store_info" : {
145            "description" : "所有门店可用,可使用小程序查看门店列表",
146            "mini_program_appid" : "wx1234567890",
147            "mini_program_path" : "/pages/index/store-list"
148          }
149        },
150        "coupon_display_info" : {
151          "code_display_mode" : "QRCODE",
152          "background_color" : "Color010",
153          "entrance_mini_program" : {
154            "appid" : "wx1234567890",
155            "path" : "/pages/index/product",
156            "entrance_wording" : "欢迎选购",
157            "guidance_wording" : "获取更多优惠"
158          },
159          "entrance_official_account" : {
160            "appid" : "wx1234567890"
161          }
162        },
163        "notify_config" : {
164          "notify_appid" : "wx4fd12345678"
165        },
166        "store_scope" : "NONE",
167        "sent_count_info" : {
168          "total_count" : 0,
169          "today_count" : 0
170        },
171        "state" : "SENDING"
172      },
173      {
174        "product_coupon_id" : "1000000014",
175        "stock_id" : "1000000014003",
176        "remark" : "8月工作日有效批次",
177        "coupon_code_mode" : "UPLOAD",
178        "coupon_code_count_info" : {
179          "total_count" : 0,
180          "available_count" : 0
181        },
182        "stock_send_rule" : {
183          "max_count" : 10000000,
184          "max_count_per_user" : 1
185        },
186        "progressive_bundle_usage_rule" : {
187          "coupon_available_period" : {
188            "available_begin_time" : "2025-08-01T00:00:00+08:00",
189            "available_end_time" : "2025-08-31T23:59:59+08:00",
190            "available_days" : 30,
191            "weekly_available_period" : {
192              "day_list" : [
193                "MONDAY",
194                "TUESDAY",
195                "WEDNESDAY",
196                "THURSDAY",
197                "FRIDAY"
198              ]
199            }
200          },
201          "discount_coupon" : {
202            "threshold" : 10000,
203            "percent_off" : 30
204          }
205        },
206        "stock_bundle_info" : {
207          "stock_bundle_id" : "712315129419284901",
208          "stock_bundle_index" : 2
209        },
210        "usage_rule_display_info" : {
211          "coupon_usage_method_list" : [
212            "OFFLINE",
213            "MINI_PROGRAM",
214            "PAYMENT_CODE"
215          ],
216          "mini_program_appid" : "wx1234567890",
217          "mini_program_path" : "/pages/index/product",
218          "usage_description" : "工作日可用",
219          "coupon_available_store_info" : {
220            "description" : "所有门店可用,可使用小程序查看门店列表",
221            "mini_program_appid" : "wx1234567890",
222            "mini_program_path" : "/pages/index/store-list"
223          }
224        },
225        "coupon_display_info" : {
226          "code_display_mode" : "QRCODE",
227          "background_color" : "Color010",
228          "entrance_mini_program" : {
229            "appid" : "wx1234567890",
230            "path" : "/pages/index/product",
231            "entrance_wording" : "欢迎选购",
232            "guidance_wording" : "获取更多优惠"
233          },
234          "entrance_official_account" : {
235            "appid" : "wx1234567890"
236          }
237        },
238        "notify_config" : {
239          "notify_appid" : "wx4fd12345678"
240        },
241        "store_scope" : "NONE",
242        "sent_count_info" : {
243          "total_count" : 0,
244          "today_count" : 0
245        },
246        "state" : "SENDING"
247      }
248    ]
249  }
250}

 

错误码

以下是本接口返回的错误码列表。详细错误码规则,请参考微信支付接口规则-错误码和错误提示

状态码

错误码

描述

解决方案

400

PARAM_ERROR

参数错误

请根据错误提示正确传入参数

400

INVALID_REQUEST

HTTP 请求不符合微信支付 APIv3 接口规则

请参阅 接口规则

401

SIGN_ERROR

验证不通过

请参阅 签名常见问题

500

SYSTEM_ERROR

系统异常,请稍后重试

请稍后重试

400

PARAM_ERROR

缺少必填参数`app_jump_type`

查看文档填写`app_jump_type`

400

PARAM_ERROR

商品券APP跳转类型为口令链接时,必须提供「口令链接」

请在 usage_rule_display_info 中设置 passcode_link 字段

400

INVALID_REQUEST

发放类型无效,当前仅支持盲盒领取模式

不支持当前的玩法类型

403

NO_AUTH

品牌没有申请盲盒领取模式的权限

请联系微信支付申请开通盲盒券权限

400

PARAM_ERROR

盲盒券兑换价格必须为0

请将固定兑换价格改为 0

400

PARAM_ERROR

盲盒券单品图片必填

请补充单品图片

400

PARAM_ERROR

盲盒券单品ID必填

请补充单品标识

400

PARAM_ERROR

盲盒券必须是兑换券类型

请将商品券类型改为兑换券

400

INVALID_REQUEST

当前品牌未配置商品券事件通知地址,请先调用「设置商品券事件通知地址」设置通知地址后再执行此操作

请先调用「设置商品券事件通知地址」设置通知地址后再执行此操作

400

INVALID_REQUEST

商品券使用模式(usage_mode)非法,不可以使此模式

请使用其他 usage_mode

400

INVALID_REQUEST

usage_mode 为 SINGLE 时,批次未填写 single_usage_rule

请填写 single_usage_rule

400

INVALID_REQUEST

usage_mode 为 SEQUENTIAL 时,批次未填写 sequential_usage_rule

请填写 sequential_usage_rule

400

INVALID_REQUEST

单券使用模式的商品券批次,应该在「单券使用规则」中包含对应类型的优惠规则。对于文档中标记不应填写的优惠规则应删除。

请在「单券使用规则」中包含对应类型的优惠规则,并删除文档中标记不应填写的优惠规则。

400

INVALID_REQUEST

多次优惠使用模式的商品券批次,应该在「多次优惠使用规则」中包含对应类型的优惠规则,且数量与多次优惠的优惠次数相等

在「多次优惠使用规则」中包含对应类型的优惠规则,且数量与多次优惠的优惠次数相等

400

INVALID_REQUEST

单品满减券或单品折扣券不应在商品券中设置「满减券使用规则」或「折扣券使用规则」,而是应该在商品券批次中设置

请删除商品券中的「满减券使用规则」或「折扣券使用规则」,并在商品券批次中设置对应的优惠规则

403

NO_AUTH

品牌没有此接口权限

品牌没有此接口权限

409

ABORTED

数据正在修改中,无法操作,请稍后再重试

请稍后再重试

400

PARAM_ERROR

参数错误,请参照API文档确认参数后再调用

参数错误,请确认请求参数是否包含接口未定义的字段,传递的参数值是否符合要求

400

INVALID_REQUEST

商品券已失效

商品券已失效

400

ALREADY_EXISTS

请求单号重复

请更换请求单号后重试

400

INVALID_REQUEST

商品券支持APP核销时,必须提供「APP跳转路径」

请提供「APP跳转路径」参数

400

PARAM_ERROR

分页大小超出限制,请根据接口文档调整到允许的范围

请调整分页大小到规定范围

400

INVALID_REQUEST

商品券支持小程序核销时,必须提供「小程序AppID」

请提供「小程序AppID」

400

INVALID_REQUEST

单品券必须提供商品原价,请补充

请补充商品原价

400

INVALID_REQUEST

商品券支持小程序核销时,必须提供「小程序跳转路径」

请提供提供「小程序跳转路径」

400

PARAM_ERROR

时间字符串格式错误,请使用 RFC3339 标准格式

请使用 RFC3339 标准格式

400

INVALID_REQUEST

单券模式下,全场满减券应在商品券中提供满减券使用规则信息

请在商品券中提供「满减券使用规则信息」

400

INVALID_REQUEST

每周固定可用时间(weekly_available_period)中提供当天可用时间段时(day_period_list),每周可用星期数(day_list)必填

请补充 每周可用星期数(day_list)

400

INVALID_REQUEST

单券模式下,全场券需要提供「单券模式信息(single_usage_info)」

请提供单券模式信息(single_usage_info)

400

INVALID_REQUEST

传入的OpenID不合法

请使用参数 AppID 对应的的OpenID

400

INVALID_REQUEST

内容中包含敏感词或敏感图片,请修改后再重试

请修改内容后再重试

400

PARAM_ERROR

缺少必要的商品券图片

缺少必要的商品券图片,请根据API文档在传递的请求参数中补充该参数

400

PARAM_ERROR

缺少必要的商品券背景图

缺少商品券展示信息中的商品券背景图,请上传商品券背景图

400

PARAM_ERROR

缺少单品数量

请求参数缺少单品数量,请上传单品数量

400

PARAM_ERROR

参数错误,请根据接口文档检查字段要求

请根据接口文档检查字段要求,修复参数后重试

400

PARAM_ERROR

Http header中缺少必填参数Wechatpay-Serial

缺少必要商品券图片,请补充上传后重试

400

PARAM_ERROR

参数过短

请参考文档中对每个字段的要求以及组合要求,确认请求参数是否满足

400

PARAM_ERROR

参数过长

请参考文档中对每个字段的要求以及组合要求,确认请求参数是否满足

400

PARAM_ERROR

参数错误

请参考文档中对每个字段的要求以及组合要求,确认请求参数是否满足

400

PARAM_ERROR

参数超出取值范围

请参考文档中对每个字段的要求以及组合要求,确认请求参数是否满足

401

SIGN_ERROR

Http头Authorization值格式错误,请参考《微信支付商户REST API签名规则》

Http头Authorization值格式错误,请参考《APIv3如何签名和验签》,检查传递的Authorization值是否符合规则

400

INVALID_REQUEST

Http头Content-Type值必须为application/json

需将Http头中的Content-Type值设置为application/json

401

SIGN_ERROR

Http头Authorization中的timestamp与发起请求的时间不得超过5分钟

Authorization 头 timestamp 与请求时间间隔超 5 分钟,需重新生成timestamp并替换该字段后重试。

401

SIGN_ERROR

Authorization不合法

Http头未传递Authorization值或Authorization值格式错误,请参考《APIv3如何签名和验签》,检查传递的Authorization值是否符合规则

400

INVALID_REQUEST

Http头缺少Accept或User-Agent

Http头缺少Accept或User-Agent,请根据API文档在请求头中补充该参数

400

PARAM_ERROR

请求中含有未在API文档中定义的参数

请求中含有未在API文档中定义的参数,请检查传递的参数列表是否有编写错误的字段名

401

SIGN_ERROR

Http头Authorization认证类型不正确

Http头Authorization认证类型不正确,请将认证类型修改为WECHATPAY-BRAND-SHA256-RSA2048

 

 

反馈
目录
置顶