创建商品券

更新时间:2025.08.04

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

频率限制:接口级限制1000/min

接口说明

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

请求方式:【POST】/v3/marketing/partner/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


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

【批次】 商品券批次信息

属性

 brand_id  必填   string

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

请求示例

curl
Java
Go

POST

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

1curl -X POST \
2  https://api.mch.weixin.qq.com/v3/marketing/partner/product-coupon/product-coupons \
3  -H "Authorization: WECHATPAY2-SHA256-RSA2048 mchid=\"1900000001\",..." \
4  -H "Accept: application/json" \
5  -H "Content-Type: application/json" \
6  -d '{
7    "out_product_no" : "Product_1234567890",
8    "scope" : "ALL",
9    "usage_mode" : "SINGLE",
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    "single_usage_info" : {
19      "discount_coupon" : {
20        "threshold" : 10000,
21        "percent_off" : 20
22      }
23    },
24    "type" : "DISCOUNT",
25    "stock" : {
26      "remark" : "8月工作日有效批次",
27      "coupon_code_mode" : "UPLOAD",
28      "stock_send_rule" : {
29        "max_count" : 10000000,
30        "max_count_per_user" : 1
31      },
32      "single_usage_rule" : {
33        "coupon_available_period" : {
34          "available_begin_time" : "2025-08-01T00:00:00+08:00",
35          "available_end_time" : "2025-08-31T23:59:59+08:00",
36          "available_days" : 30,
37          "weekly_available_period" : {
38            "day_list" : [
39              "MONDAY",
40              "TUESDAY",
41              "WEDNESDAY",
42              "THURSDAY",
43              "FRIDAY"
44            ]
45          }
46        }
47      },
48      "usage_rule_display_info" : {
49        "coupon_usage_method_list" : [
50          "OFFLINE",
51          "MINI_PROGRAM",
52          "PAYMENT_CODE"
53        ],
54        "mini_program_appid" : "wx1234567890",
55        "mini_program_path" : "/pages/index/product",
56        "usage_description" : "工作日可用",
57        "coupon_available_store_info" : {
58          "description" : "所有门店可用,可使用小程序查看门店列表",
59          "mini_program_appid" : "wx1234567890",
60          "mini_program_path" : "/pages/index/store-list"
61        }
62      },
63      "coupon_display_info" : {
64        "code_display_mode" : "QRCODE",
65        "background_color" : "Color010",
66        "entrance_mini_program" : {
67          "appid" : "wx1234567890",
68          "path" : "/pages/index/product",
69          "entrance_wording" : "欢迎选购",
70          "guidance_wording" : "获取更多优惠"
71        },
72        "entrance_official_account" : {
73          "appid" : "wx1234567890"
74        },
75        "entrance_finder" : {
76          "finder_id" : "gh_12345678",
77          "finder_video_id" : "UDFsdf24df34dD456Hdf34",
78          "finder_video_cover_image_url" : "https://wxpaylogo.qpic.cn/wxpaylogo/xxxxx/xxx"
79        }
80      },
81      "store_scope" : "NONE",
82      "notify_config" : {
83        "notify_appid" : "wx4fd12345678"
84      }
85    },
86    "out_request_no" : "12345_20250101_A3489",
87    "brand_id" : "120344"
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

【批次】 商品券批次信息

属性

 brand_id  必填   string

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

应答示例

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    "brand_id" : "120344"
94  },
95  "brand_id" : "120344"
96}
97

 

错误码

公共错误码

状态码

错误码

描述

解决方案

400

PARAM_ERROR

参数错误

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

400

INVALID_REQUEST

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

请参阅 接口规则

401

SIGN_ERROR

验证不通过

请参阅 签名常见问题

500

SYSTEM_ERROR

系统异常,请稍后重试

请稍后重试

业务错误码

状态码

错误码

描述

解决方案

400

INVALID_REQUEST

传入参数不符合业务规则

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

400

ALREADY_EXISTS

商品券已存在

确认 out_request_no 字段是否重复使用,确保不同请求的 out_request_no 唯一

403

NO_AUTH

缺少业务相关权限

请确认已开通商品券权限

429

RATELIMIT_EXCEEDED

请求超过接口频率限制

请稍后使用原参数重试

 

反馈
咨询
目录
置顶