创建商品券

更新时间:2025.08.05

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

频率限制:20/s

接口说明

支持商户:【品牌商户】

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

请求域名:【主域名】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、调用含有敏感信息参数(如姓名、身份证号码)的接口时,需要使用微信支付公钥加密敏感信息后再传输参数,加密指引请参考微信支付公钥加密敏感信息指引


body  包体参数

 out_request_no  必填   string(40)

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


 scope  必填   string

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

可选取值

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

  • SINGLE:  单品券,此时券类型 type 配置不受限制,即可配置为 NORMALDISCOUNT 或 EXCHANGE


 type  必填   string

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

可选取值

  • NORMAL:  满减券

  • DISCOUNT:  折扣券

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


 usage_mode  必填   string

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

可选取值

  • SINGLE:  单券,即用户只能使用一次,使用后券失效

  • SEQUENTIAL:  多次优惠,即用户可以按顺序多次使用,每次核销成功后会发放下一次优惠机会,直到用完为止


 single_usage_info  选填   object

【单券模式信息】 单券模式配置信息,当且仅当 usage_mode 为 SINGLE 时选填(是否填写取决于是否需要填写内部字段),其他模式不应填写。

属性

 sequential_usage_info  选填   object

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

属性

 display_info  必填   object

【展示信息】 商品券展示信息,展示结果可参考商品券示意图

属性

 out_product_no  选填   string(40)

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

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


 stock  必填   object

【批次】 商品券批次信息

属性

请求示例

curl
Java
Go

POST

创建满100可用的全场8折券

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

应答参数

200 OK

 product_coupon_id  必填   string(40)

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


 scope  必填   string

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

可选取值

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

  • SINGLE:  单品券,此时券类型 type 配置不受限制,即可配置为 NORMALDISCOUNT 或 EXCHANGE


 type  必填   string

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

可选取值

  • NORMAL:  满减券

  • DISCOUNT:  折扣券

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


 usage_mode  必填   string

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

可选取值

  • SINGLE:  单券,即用户只能使用一次,使用后券失效

  • SEQUENTIAL:  多次优惠,即用户可以按顺序多次使用,每次核销成功后会发放下一次优惠机会,直到用完为止


 single_usage_info  选填   object

【单券模式信息】 单券模式配置信息,仅当 usage_mode 为 SINGLE 时提供,其他场景不提供。

属性

 sequential_usage_info  选填   object

【多次优惠模式信息】 多次优惠模式配置信息,当且仅当 usage_mode 为 SEQUENTIAL 时提供,其他模式不提供。

属性

 display_info  必填   object

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

属性

 out_product_no  选填   string

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


 state  必填   string

【商品券状态】 商品券状态

可选取值

  • AUDITING:  审批中,审批完成前商品券不可用

  • EFFECTIVE:  生效中,商品券已生效,可以正常使用

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


 stock  必填   object

【批次】 商品券批次信息

属性

应答示例

200 OK

创建满100可用的全场8折券

1{
2  "product_coupon_id" : "1000000013",
3  "scope" : "ALL",
4  "type" : "DISCOUNT",
5  "usage_mode" : "SINGLE",
6  "single_usage_info" : {
7    "discount_coupon" : {
8      "threshold" : 10000,
9      "percent_off" : 20
10    }
11  },
12  "display_info" : {
13    "name" : "全场满100立打8折",
14    "image_url" : "https://wxpaylogo.qpic.cn/wxpaylogo/xxxxx/xxx",
15    "background_url" : "https://wxpaylogo.qpic.cn/wxpaylogo/xxxxx/xxx",
16    "detail_image_url_list" : [
17      "https://wxpaylogo.qpic.cn/wxpaylogo/xxxxx/xxx"
18    ]
19  },
20  "state" : "EFFECTIVE",
21  "out_product_no" : "Product_1234567890",
22  "stock" : {
23    "product_coupon_id" : "1000000013",
24    "stock_id" : "1000000013001",
25    "remark" : "8月工作日有效批次",
26    "coupon_code_mode" : "UPLOAD",
27    "coupon_code_count_info" : {
28      "total_count" : 0,
29      "available_count" : 0
30    },
31    "stock_send_rule" : {
32      "max_count" : 10000000,
33      "max_count_per_user" : 1
34    },
35    "single_usage_rule" : {
36      "coupon_available_period" : {
37        "available_begin_time" : "2025-08-01T00:00:00+08:00",
38        "available_end_time" : "2025-08-31T23:59:59+08:00",
39        "available_days" : 30,
40        "weekly_available_period" : {
41          "day_list" : [
42            "MONDAY",
43            "TUESDAY",
44            "WEDNESDAY",
45            "THURSDAY",
46            "FRIDAY"
47          ]
48        }
49      }
50    },
51    "usage_rule_display_info" : {
52      "coupon_usage_method_list" : [
53        "OFFLINE",
54        "MINI_PROGRAM",
55        "PAYMENT_CODE"
56      ],
57      "mini_program_appid" : "wx1234567890",
58      "mini_program_path" : "/pages/index/product",
59      "usage_description" : "工作日可用",
60      "coupon_available_store_info" : {
61        "description" : "所有门店可用,可使用小程序查看门店列表",
62        "mini_program_appid" : "wx1234567890",
63        "mini_program_path" : "/pages/index/store-list"
64      }
65    },
66    "coupon_display_info" : {
67      "code_display_mode" : "QRCODE",
68      "background_color" : "Color010",
69      "entrance_mini_program" : {
70        "appid" : "wx1234567890",
71        "path" : "/pages/index/product",
72        "entrance_wording" : "欢迎选购",
73        "guidance_wording" : "获取更多优惠"
74      },
75      "entrance_official_account" : {
76        "appid" : "wx1234567890"
77      },
78      "entrance_finder" : {
79        "finder_id" : "gh_12345678",
80        "finder_video_id" : "UDFsdf24df34dD456Hdf34",
81        "finder_video_cover_image_url" : "https://wxpaylogo.qpic.cn/wxpaylogo/xxxxx/xxx"
82      }
83    },
84    "notify_config" : {
85      "notify_appid" : "wx4fd12345678"
86    },
87    "store_scope" : "NONE",
88    "sent_count_info" : {
89      "total_count" : 0,
90      "today_count" : 0
91    },
92    "state" : "SENDING"
93  }
94}
95

 

错误码

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

状态码

错误码

描述

解决方案

400

PARAM_ERROR

参数错误

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

400

INVALID_REQUEST

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

请参阅 接口规则

401

SIGN_ERROR

验证不通过

请参阅 签名常见问题

500

SYSTEM_ERROR

系统异常,请稍后重试

请稍后重试

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

品牌没有此接口权限

品牌没有此接口权限

400

INVALID_REQUEST

全场券的券类型只能设置为 「满减券」和「折扣券」,不可以设置为「换购券」

请更换券类型为「满减券」或「折扣券」;或者更换券使用范围为「单品券』

400

INVALID_REQUEST

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

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

400

PARAM_ERROR

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

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

400

INVALID_REQUEST

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

请提供「小程序AppID」

400

INVALID_REQUEST

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

请补充商品原价

400

INVALID_REQUEST

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

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

400

INVALID_REQUEST

单品券必须提供商品券套餐组合信息,请补充

请提供商品券套餐组合信息

400

PARAM_ERROR

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

请使用 RFC3339 标准格式

400

INVALID_REQUEST

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

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

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

多次优惠模式下必须提供「多次优惠模式信息(sequential_usage_info)」

请填写 多次优惠模式信息(sequential_usage_info)

400

INVALID_REQUEST

传入的OpenID不合法

请使用参数 AppID 对应的的OpenID

 

元宝AI
反馈
目录
置顶