添加商品券批次
更新时间:2025.08.28品牌方可以通过该接口为已有的商品券添加更多批次,多个批次可以实现品牌方多样化的投放需求。
注:同一个商品券下,最多只能有200个生效中的批次,已过期和已失效的批次不计入统计。
前置条件:商品券处于 EFFECTIVE 状态
频率限制:20/s
接口说明
支持商户:【品牌商户】
请求方式:【POST】/brand/marketing/product-coupon/product-coupons/{product_coupon_id}/stocks
请求域名:【主域名】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、调用含有敏感信息参数(如姓名、身份证号码)的接口时,需要使用微信支付公钥加密敏感信息后再传输参数,加密指引请参考微信支付公钥加密敏感信息指引。
path 路径参数
product_coupon_id 必填 string
【商品券ID】 商品券的唯一标识,创建商品券时由微信支付生成
body 包体参数
out_request_no 必填 string(40)
【创建请求单号】 品牌创建批次请求流水号,品牌侧需保持唯一性,可使用 数字、大小写字母、下划线_、短横线- 组成,长度在6-40个字符之间
stock 必填 object
【批次】 为商品券创建的批次详情
| 属性 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
remark 选填 string(20) 【备注】 仅配置品牌方可见,用于自定义信息,最多20个UTF-8字符 coupon_code_mode 必填 string 【券Code分配模式】 决定发券时用户商品券Code如何产生 可选取值
stock_send_rule 必填 object 【发放规则】 批次的发放规则
single_usage_rule 选填 object 【单券使用规则】 当且仅当
sequential_usage_rule 选填 object 【多次优惠使用规则】 当且仅当
usage_rule_display_info 必填 object 【券使用规则展示信息】 券使用规则展示信息
coupon_display_info 必填 object 【用户商品券展示信息】 用户商品券在卡包中的展示详情,包括引导用户的自定义入口
notify_config 必填 object 【事件通知配置】 发生券相关事件时,微信支付会向品牌方发送通知,需要提供通知相关配置
store_scope 必填 string 【可用门店范围】 控制该批次可以在品牌下哪些门店使用 可选取值
|
请求示例
POST
1curl -X POST \ 2 https://api.mch.weixin.qq.com/brand/marketing/product-coupon/product-coupons/200000001/stocks \ 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_request_no" : "34657_20250101_123456", 9 "stock" : { 10 "remark" : "满减券", 11 "coupon_code_mode" : "UPLOAD", 12 "stock_send_rule" : { 13 "max_count" : 10000000, 14 "max_count_per_day" : 10000, 15 "max_count_per_user" : 1 16 }, 17 "single_usage_rule" : { 18 "coupon_available_period" : { 19 "available_begin_time" : "2025-01-01T00:00:00+08:00", 20 "available_end_time" : "2025-10-01T00:00:00+08:00", 21 "available_days" : 10, 22 "wait_days_after_receive" : 1, 23 "weekly_available_period" : { 24 "day_list" : [ 25 "MONDAY" 26 ], 27 "day_period_list" : [ 28 { 29 "begin_time" : 60, 30 "end_time" : 86399 31 } 32 ] 33 }, 34 "irregular_available_period_list" : [ 35 { 36 "begin_time" : "2025-01-01T00:00:00+08:00", 37 "end_time" : "2025-10-01T00:00:00+08:00" 38 } 39 ] 40 }, 41 "normal_coupon" : { 42 "threshold" : 10000, 43 "discount_amount" : 100 44 }, 45 "discount_coupon" : { 46 "threshold" : 10000, 47 "percent_off" : 30 48 }, 49 "exchange_coupon" : { 50 "threshold" : 10000, 51 "exchange_price" : 100 52 } 53 }, 54 "sequential_usage_rule" : { 55 "coupon_available_period" : { 56 "available_begin_time" : "2025-01-01T00:00:00+08:00", 57 "available_end_time" : "2025-10-01T00:00:00+08:00", 58 "wait_days_after_receive" : 1, 59 "weekly_available_period" : { 60 "day_list" : [ 61 "MONDAY" 62 ], 63 "day_period_list" : [ 64 { 65 "begin_time" : 60, 66 "end_time" : 86399 67 } 68 ] 69 }, 70 "irregular_available_period_list" : [ 71 { 72 "begin_time" : "2025-01-01T00:00:00+08:00", 73 "end_time" : "2025-10-01T00:00:00+08:00" 74 } 75 ] 76 }, 77 "normal_coupon_list" : [ 78 { 79 "threshold" : 10000, 80 "discount_amount" : 100 81 } 82 ], 83 "discount_coupon_list" : [ 84 { 85 "threshold" : 10000, 86 "percent_off" : 30 87 } 88 ], 89 "exchange_coupon_list" : [ 90 { 91 "threshold" : 10000, 92 "exchange_price" : 100 93 } 94 ], 95 "special_first" : false 96 }, 97 "usage_rule_display_info" : { 98 "coupon_usage_method_list" : [ 99 "MINI_PROGRAM" 100 ], 101 "mini_program_appid" : "wx1234567890", 102 "mini_program_path" : "/pages/index/product", 103 "app_path" : "https://www.example.com/jump-to-app", 104 "usage_description" : "全场可用", 105 "coupon_available_store_info" : { 106 "description" : "可在上海市区的所有门店使用,详细列表参考小程序内信息为准", 107 "mini_program_appid" : "wx1234567890", 108 "mini_program_path" : "/pages/index/store-list" 109 } 110 }, 111 "coupon_display_info" : { 112 "code_display_mode" : "QRCODE", 113 "background_color" : "Color010", 114 "entrance_mini_program" : { 115 "appid" : "wx1234567890", 116 "path" : "/pages/index/product", 117 "entrance_wording" : "欢迎选购", 118 "guidance_wording" : "获取更多优惠" 119 }, 120 "entrance_official_account" : { 121 "appid" : "wx1234567890" 122 }, 123 "entrance_finder" : { 124 "finder_id" : "gh_12345678", 125 "finder_video_id" : "UDFsdf24df34dD456Hdf34", 126 "finder_video_cover_image_url" : "https://wxpaylogo.qpic.cn/wxpaylogo/xxxxx/xxx" 127 } 128 }, 129 "notify_config" : { 130 "notify_appid" : "wx4fd12345678" 131 }, 132 "store_scope" : "SPECIFIC" 133 } 134 }' 135
需配合微信支付工具库 WXPayUtility 使用,请参考Java
1package com.java.demo; 2 3import com.java.utils.WXPayBrandUtility; // 引用微信支付工具库,参考:https://pay.weixin.qq.com/doc/brand/4015826861 4 5import com.google.gson.annotations.SerializedName; 6import com.google.gson.annotations.Expose; 7import okhttp3.MediaType; 8import okhttp3.OkHttpClient; 9import okhttp3.Request; 10import okhttp3.RequestBody; 11import okhttp3.Response; 12 13import java.io.IOException; 14import java.io.UncheckedIOException; 15import java.security.PrivateKey; 16import java.security.PublicKey; 17import java.util.ArrayList; 18import java.util.HashMap; 19import java.util.List; 20import java.util.Map; 21 22/** 23 * 添加商品券批次 24 */ 25public class CreateStock { 26 private static String HOST = "https://api.mch.weixin.qq.com"; 27 private static String METHOD = "POST"; 28 private static String PATH = "/brand/marketing/product-coupon/product-coupons/{product_coupon_id}/stocks"; 29 30 public static void main(String[] args) { 31 // TODO: 请准备商户开发必要参数,参考:https://pay.weixin.qq.com/doc/brand/4015415289 32 CreateStock client = new CreateStock( 33 "xxxxxxxx", // 品牌ID,是由微信支付系统生成并分配给每个品牌方的唯一标识符,品牌ID获取方式参考 https://pay.weixin.qq.com/doc/brand/4015415289 34 "1DDE55AD98Exxxxxxxxxx", // 品牌API证书序列号,如何获取请参考 https://pay.weixin.qq.com/doc/brand/4015407570 35 "/path/to/apiclient_key.pem", // 品牌API证书私钥文件路径,本地文件路径 36 "PUB_KEY_ID_xxxxxxxxxxxxx", // 微信支付公钥ID,如何获取请参考 https://pay.weixin.qq.com/doc/brand/4015453439 37 "/path/to/wxp_pub.pem" // 微信支付公钥文件路径,本地文件路径 38 ); 39 40 CreateStockRequest request = new CreateStockRequest(); 41 request.productCouponId = "200000001"; 42 request.outRequestNo = "34657_20250101_123456"; 43 request.stock = new StockForCreate(); 44 request.stock.remark = "满减券"; 45 request.stock.couponCodeMode = CouponCodeMode.UPLOAD; 46 request.stock.stockSendRule = new StockSendRule(); 47 request.stock.stockSendRule.maxCount = 10000000L; 48 request.stock.stockSendRule.maxCountPerDay = 10000L; 49 request.stock.stockSendRule.maxCountPerUser = 1L; 50 request.stock.singleUsageRule = new SingleUsageRule(); 51 request.stock.singleUsageRule.couponAvailablePeriod = new SingleCouponAvailablePeriod(); 52 request.stock.singleUsageRule.couponAvailablePeriod.availableBeginTime = "2025-01-01T00:00:00+08:00"; 53 request.stock.singleUsageRule.couponAvailablePeriod.availableEndTime = "2025-10-01T00:00:00+08:00"; 54 request.stock.singleUsageRule.couponAvailablePeriod.availableDays = 10L; 55 request.stock.singleUsageRule.couponAvailablePeriod.waitDaysAfterReceive = 1L; 56 request.stock.singleUsageRule.couponAvailablePeriod.weeklyAvailablePeriod = new FixedWeekPeriod(); 57 request.stock.singleUsageRule.couponAvailablePeriod.weeklyAvailablePeriod.dayList = new ArrayList<>(); 58 { 59 request.stock.singleUsageRule.couponAvailablePeriod.weeklyAvailablePeriod.dayList.add(WeekEnum.MONDAY); 60 }; 61 request.stock.singleUsageRule.couponAvailablePeriod.weeklyAvailablePeriod.dayPeriodList = new ArrayList<>(); 62 { 63 PeriodOfTheDay dayPeriodListItem = new PeriodOfTheDay(); 64 dayPeriodListItem.beginTime = 60L; 65 dayPeriodListItem.endTime = 86399L; 66 request.stock.singleUsageRule.couponAvailablePeriod.weeklyAvailablePeriod.dayPeriodList.add(dayPeriodListItem); 67 }; 68 request.stock.singleUsageRule.couponAvailablePeriod.irregularAvailablePeriodList = new ArrayList<>(); 69 { 70 TimePeriod irregularAvailablePeriodListItem = new TimePeriod(); 71 irregularAvailablePeriodListItem.beginTime = "2025-01-01T00:00:00+08:00"; 72 irregularAvailablePeriodListItem.endTime = "2025-10-01T00:00:00+08:00"; 73 request.stock.singleUsageRule.couponAvailablePeriod.irregularAvailablePeriodList.add(irregularAvailablePeriodListItem); 74 }; 75 request.stock.singleUsageRule.normalCoupon = new NormalCouponUsageRule(); 76 request.stock.singleUsageRule.normalCoupon.threshold = 10000L; 77 request.stock.singleUsageRule.normalCoupon.discountAmount = 100L; 78 request.stock.singleUsageRule.discountCoupon = new DiscountCouponUsageRule(); 79 request.stock.singleUsageRule.discountCoupon.threshold = 10000L; 80 request.stock.singleUsageRule.discountCoupon.percentOff = 30L; 81 request.stock.singleUsageRule.exchangeCoupon = new ExchangeCouponUsageRule(); 82 request.stock.singleUsageRule.exchangeCoupon.threshold = 10000L; 83 request.stock.singleUsageRule.exchangeCoupon.exchangePrice = 100L; 84 request.stock.sequentialUsageRule = new SequentialUsageRule(); 85 request.stock.sequentialUsageRule.couponAvailablePeriod = new SequentialCouponAvailablePeriod(); 86 request.stock.sequentialUsageRule.couponAvailablePeriod.availableBeginTime = "2025-01-01T00:00:00+08:00"; 87 request.stock.sequentialUsageRule.couponAvailablePeriod.availableEndTime = "2025-10-01T00:00:00+08:00"; 88 request.stock.sequentialUsageRule.couponAvailablePeriod.waitDaysAfterReceive = 1L; 89 request.stock.sequentialUsageRule.couponAvailablePeriod.weeklyAvailablePeriod = new FixedWeekPeriod(); 90 request.stock.sequentialUsageRule.couponAvailablePeriod.weeklyAvailablePeriod.dayList = new ArrayList<>(); 91 { 92 request.stock.sequentialUsageRule.couponAvailablePeriod.weeklyAvailablePeriod.dayList.add(WeekEnum.MONDAY); 93 }; 94 request.stock.sequentialUsageRule.couponAvailablePeriod.weeklyAvailablePeriod.dayPeriodList = new ArrayList<>(); 95 { 96 PeriodOfTheDay dayPeriodListItem = new PeriodOfTheDay(); 97 dayPeriodListItem.beginTime = 60L; 98 dayPeriodListItem.endTime = 86399L; 99 request.stock.sequentialUsageRule.couponAvailablePeriod.weeklyAvailablePeriod.dayPeriodList.add(dayPeriodListItem); 100 }; 101 request.stock.sequentialUsageRule.couponAvailablePeriod.irregularAvailablePeriodList = new ArrayList<>(); 102 { 103 TimePeriod irregularAvailablePeriodListItem = new TimePeriod(); 104 irregularAvailablePeriodListItem.beginTime = "2025-01-01T00:00:00+08:00"; 105 irregularAvailablePeriodListItem.endTime = "2025-10-01T00:00:00+08:00"; 106 request.stock.sequentialUsageRule.couponAvailablePeriod.irregularAvailablePeriodList.add(irregularAvailablePeriodListItem); 107 }; 108 request.stock.sequentialUsageRule.normalCouponList = new ArrayList<>(); 109 { 110 NormalCouponUsageRule normalCouponListItem = new NormalCouponUsageRule(); 111 normalCouponListItem.threshold = 10000L; 112 normalCouponListItem.discountAmount = 100L; 113 request.stock.sequentialUsageRule.normalCouponList.add(normalCouponListItem); 114 }; 115 request.stock.sequentialUsageRule.discountCouponList = new ArrayList<>(); 116 { 117 DiscountCouponUsageRule discountCouponListItem = new DiscountCouponUsageRule(); 118 discountCouponListItem.threshold = 10000L; 119 discountCouponListItem.percentOff = 30L; 120 request.stock.sequentialUsageRule.discountCouponList.add(discountCouponListItem); 121 }; 122 request.stock.sequentialUsageRule.exchangeCouponList = new ArrayList<>(); 123 { 124 ExchangeCouponUsageRule exchangeCouponListItem = new ExchangeCouponUsageRule(); 125 exchangeCouponListItem.threshold = 10000L; 126 exchangeCouponListItem.exchangePrice = 100L; 127 request.stock.sequentialUsageRule.exchangeCouponList.add(exchangeCouponListItem); 128 }; 129 request.stock.sequentialUsageRule.specialFirst = false; 130 request.stock.usageRuleDisplayInfo = new UsageRuleDisplayInfo(); 131 request.stock.usageRuleDisplayInfo.couponUsageMethodList = new ArrayList<>(); 132 { 133 request.stock.usageRuleDisplayInfo.couponUsageMethodList.add(CouponUsageMethod.OFFLINE); 134 }; 135 request.stock.usageRuleDisplayInfo.miniProgramAppid = "wx1234567890"; 136 request.stock.usageRuleDisplayInfo.miniProgramPath = "/pages/index/product"; 137 request.stock.usageRuleDisplayInfo.appPath = "https://www.example.com/jump-to-app"; 138 request.stock.usageRuleDisplayInfo.usageDescription = "全场可用"; 139 request.stock.usageRuleDisplayInfo.couponAvailableStoreInfo = new CouponAvailableStoreInfo(); 140 request.stock.usageRuleDisplayInfo.couponAvailableStoreInfo.description = "可在上海市区的所有门店使用,详细列表参考小程序内信息为准"; 141 request.stock.usageRuleDisplayInfo.couponAvailableStoreInfo.miniProgramAppid = "wx1234567890"; 142 request.stock.usageRuleDisplayInfo.couponAvailableStoreInfo.miniProgramPath = "/pages/index/store-list"; 143 request.stock.couponDisplayInfo = new CouponDisplayInfo(); 144 request.stock.couponDisplayInfo.codeDisplayMode = CouponCodeDisplayMode.QRCODE; 145 request.stock.couponDisplayInfo.backgroundColor = "Color010"; 146 request.stock.couponDisplayInfo.entranceMiniProgram = new EntranceMiniProgram(); 147 request.stock.couponDisplayInfo.entranceMiniProgram.appid = "wx1234567890"; 148 request.stock.couponDisplayInfo.entranceMiniProgram.path = "/pages/index/product"; 149 request.stock.couponDisplayInfo.entranceMiniProgram.entranceWording = "欢迎选购"; 150 request.stock.couponDisplayInfo.entranceMiniProgram.guidanceWording = "获取更多优惠"; 151 request.stock.couponDisplayInfo.entranceOfficialAccount = new EntranceOfficialAccount(); 152 request.stock.couponDisplayInfo.entranceOfficialAccount.appid = "wx1234567890"; 153 request.stock.couponDisplayInfo.entranceFinder = new EntranceFinder(); 154 request.stock.couponDisplayInfo.entranceFinder.finderId = "gh_12345678"; 155 request.stock.couponDisplayInfo.entranceFinder.finderVideoId = "UDFsdf24df34dD456Hdf34"; 156 request.stock.couponDisplayInfo.entranceFinder.finderVideoCoverImageUrl = "https://wxpaylogo.qpic.cn/wxpaylogo/xxxxx/xxx"; 157 request.stock.notifyConfig = new NotifyConfig(); 158 request.stock.notifyConfig.notifyAppid = "wx4fd12345678"; 159 request.stock.storeScope = StockStoreScope.SPECIFIC; 160 try { 161 StockEntity response = client.run(request); 162 // TODO: 请求成功,继续业务逻辑 163 System.out.println(response); 164 } catch (WXPayBrandUtility.ApiException e) { 165 // TODO: 请求失败,根据状态码执行不同的逻辑 166 e.printStackTrace(); 167 } 168 } 169 170 public StockEntity run(CreateStockRequest request) { 171 String uri = PATH; 172 uri = uri.replace("{product_coupon_id}", WXPayBrandUtility.urlEncode(request.productCouponId)); 173 String reqBody = WXPayBrandUtility.toJson(request); 174 175 Request.Builder reqBuilder = new Request.Builder().url(HOST + uri); 176 reqBuilder.addHeader("Accept", "application/json"); 177 reqBuilder.addHeader("Wechatpay-Serial", wechatPayPublicKeyId); 178 reqBuilder.addHeader("Authorization", WXPayBrandUtility.buildAuthorization(brand_id, certificateSerialNo,privateKey, METHOD, uri, reqBody)); 179 reqBuilder.addHeader("Content-Type", "application/json"); 180 RequestBody requestBody = RequestBody.create(MediaType.parse("application/json; charset=utf-8"), reqBody); 181 reqBuilder.method(METHOD, requestBody); 182 Request httpRequest = reqBuilder.build(); 183 184 // 发送HTTP请求 185 OkHttpClient client = new OkHttpClient.Builder().build(); 186 try (Response httpResponse = client.newCall(httpRequest).execute()) { 187 String respBody = WXPayBrandUtility.extractBody(httpResponse); 188 if (httpResponse.code() >= 200 && httpResponse.code() < 300) { 189 // 2XX 成功,验证应答签名 190 WXPayBrandUtility.validateResponse(this.wechatPayPublicKeyId, this.wechatPayPublicKey, 191 httpResponse.headers(), respBody); 192 193 // 从HTTP应答报文构建返回数据 194 return WXPayBrandUtility.fromJson(respBody, StockEntity.class); 195 } else { 196 throw new WXPayBrandUtility.ApiException(httpResponse.code(), respBody, httpResponse.headers()); 197 } 198 } catch (IOException e) { 199 throw new UncheckedIOException("Sending request to " + uri + " failed.", e); 200 } 201 } 202 203 private final String brand_id; 204 private final String certificateSerialNo; 205 private final PrivateKey privateKey; 206 private final String wechatPayPublicKeyId; 207 private final PublicKey wechatPayPublicKey; 208 209 public CreateStock(String brand_id, String certificateSerialNo, String privateKeyFilePath, String wechatPayPublicKeyId, String wechatPayPublicKeyFilePath) { 210 this.brand_id = brand_id; 211 this.certificateSerialNo = certificateSerialNo; 212 this.privateKey = WXPayBrandUtility.loadPrivateKeyFromPath(privateKeyFilePath); 213 this.wechatPayPublicKeyId = wechatPayPublicKeyId; 214 this.wechatPayPublicKey = WXPayBrandUtility.loadPublicKeyFromPath(wechatPayPublicKeyFilePath); 215 } 216 217 public static class CreateStockRequest { 218 @SerializedName("out_request_no") 219 public String outRequestNo; 220 221 @SerializedName("product_coupon_id") 222 @Expose(serialize = false) 223 public String productCouponId; 224 225 @SerializedName("stock") 226 public StockForCreate stock; 227 } 228 229 public static class StockEntity { 230 @SerializedName("product_coupon_id") 231 public String productCouponId; 232 233 @SerializedName("stock_id") 234 public String stockId; 235 236 @SerializedName("remark") 237 public String remark; 238 239 @SerializedName("coupon_code_mode") 240 public CouponCodeMode couponCodeMode; 241 242 @SerializedName("coupon_code_count_info") 243 public CouponCodeCountInfo couponCodeCountInfo; 244 245 @SerializedName("stock_send_rule") 246 public StockSendRule stockSendRule; 247 248 @SerializedName("single_usage_rule") 249 public SingleUsageRule singleUsageRule; 250 251 @SerializedName("sequential_usage_rule") 252 public SequentialUsageRule sequentialUsageRule; 253 254 @SerializedName("usage_rule_display_info") 255 public UsageRuleDisplayInfo usageRuleDisplayInfo; 256 257 @SerializedName("coupon_display_info") 258 public CouponDisplayInfo couponDisplayInfo; 259 260 @SerializedName("notify_config") 261 public NotifyConfig notifyConfig; 262 263 @SerializedName("store_scope") 264 public StockStoreScope storeScope; 265 266 @SerializedName("sent_count_info") 267 public StockSentCountInfo sentCountInfo; 268 269 @SerializedName("state") 270 public StockState state; 271 272 @SerializedName("deactivate_request_no") 273 public String deactivateRequestNo; 274 275 @SerializedName("deactivate_time") 276 public String deactivateTime; 277 278 @SerializedName("deactivate_reason") 279 public String deactivateReason; 280 } 281 282 public static class StockForCreate { 283 @SerializedName("remark") 284 public String remark; 285 286 @SerializedName("coupon_code_mode") 287 public CouponCodeMode couponCodeMode; 288 289 @SerializedName("stock_send_rule") 290 public StockSendRule stockSendRule; 291 292 @SerializedName("single_usage_rule") 293 public SingleUsageRule singleUsageRule; 294 295 @SerializedName("sequential_usage_rule") 296 public SequentialUsageRule sequentialUsageRule; 297 298 @SerializedName("usage_rule_display_info") 299 public UsageRuleDisplayInfo usageRuleDisplayInfo; 300 301 @SerializedName("coupon_display_info") 302 public CouponDisplayInfo couponDisplayInfo; 303 304 @SerializedName("notify_config") 305 public NotifyConfig notifyConfig; 306 307 @SerializedName("store_scope") 308 public StockStoreScope storeScope; 309 } 310 311 public enum CouponCodeMode { 312 @SerializedName("WECHATPAY") 313 WECHATPAY, 314 @SerializedName("UPLOAD") 315 UPLOAD, 316 @SerializedName("API_ASSIGN") 317 API_ASSIGN 318 } 319 320 public static class CouponCodeCountInfo { 321 @SerializedName("total_count") 322 public Long totalCount; 323 324 @SerializedName("available_count") 325 public Long availableCount; 326 } 327 328 public static class StockSendRule { 329 @SerializedName("max_count") 330 public Long maxCount; 331 332 @SerializedName("max_count_per_day") 333 public Long maxCountPerDay; 334 335 @SerializedName("max_count_per_user") 336 public Long maxCountPerUser; 337 } 338 339 public static class SingleUsageRule { 340 @SerializedName("coupon_available_period") 341 public SingleCouponAvailablePeriod couponAvailablePeriod; 342 343 @SerializedName("normal_coupon") 344 public NormalCouponUsageRule normalCoupon; 345 346 @SerializedName("discount_coupon") 347 public DiscountCouponUsageRule discountCoupon; 348 349 @SerializedName("exchange_coupon") 350 public ExchangeCouponUsageRule exchangeCoupon; 351 } 352 353 public static class SequentialUsageRule { 354 @SerializedName("coupon_available_period") 355 public SequentialCouponAvailablePeriod couponAvailablePeriod; 356 357 @SerializedName("normal_coupon_list") 358 public List<NormalCouponUsageRule> normalCouponList; 359 360 @SerializedName("discount_coupon_list") 361 public List<DiscountCouponUsageRule> discountCouponList; 362 363 @SerializedName("exchange_coupon_list") 364 public List<ExchangeCouponUsageRule> exchangeCouponList; 365 366 @SerializedName("special_first") 367 public Boolean specialFirst; 368 } 369 370 public static class UsageRuleDisplayInfo { 371 @SerializedName("coupon_usage_method_list") 372 public List<CouponUsageMethod> couponUsageMethodList = new ArrayList<CouponUsageMethod>(); 373 374 @SerializedName("mini_program_appid") 375 public String miniProgramAppid; 376 377 @SerializedName("mini_program_path") 378 public String miniProgramPath; 379 380 @SerializedName("app_path") 381 public String appPath; 382 383 @SerializedName("usage_description") 384 public String usageDescription; 385 386 @SerializedName("coupon_available_store_info") 387 public CouponAvailableStoreInfo couponAvailableStoreInfo; 388 } 389 390 public static class CouponDisplayInfo { 391 @SerializedName("code_display_mode") 392 public CouponCodeDisplayMode codeDisplayMode; 393 394 @SerializedName("background_color") 395 public String backgroundColor; 396 397 @SerializedName("entrance_mini_program") 398 public EntranceMiniProgram entranceMiniProgram; 399 400 @SerializedName("entrance_official_account") 401 public EntranceOfficialAccount entranceOfficialAccount; 402 403 @SerializedName("entrance_finder") 404 public EntranceFinder entranceFinder; 405 } 406 407 public static class NotifyConfig { 408 @SerializedName("notify_appid") 409 public String notifyAppid; 410 } 411 412 public enum StockStoreScope { 413 @SerializedName("NONE") 414 NONE, 415 @SerializedName("ALL") 416 ALL, 417 @SerializedName("SPECIFIC") 418 SPECIFIC 419 } 420 421 public static class StockSentCountInfo { 422 @SerializedName("total_count") 423 public Long totalCount; 424 425 @SerializedName("today_count") 426 public Long todayCount; 427 } 428 429 public enum StockState { 430 @SerializedName("AUDITING") 431 AUDITING, 432 @SerializedName("SENDING") 433 SENDING, 434 @SerializedName("PAUSED") 435 PAUSED, 436 @SerializedName("STOPPED") 437 STOPPED, 438 @SerializedName("DEACTIVATED") 439 DEACTIVATED 440 } 441 442 public static class SingleCouponAvailablePeriod { 443 @SerializedName("available_begin_time") 444 public String availableBeginTime; 445 446 @SerializedName("available_end_time") 447 public String availableEndTime; 448 449 @SerializedName("available_days") 450 public Long availableDays; 451 452 @SerializedName("wait_days_after_receive") 453 public Long waitDaysAfterReceive; 454 455 @SerializedName("weekly_available_period") 456 public FixedWeekPeriod weeklyAvailablePeriod; 457 458 @SerializedName("irregular_available_period_list") 459 public List<TimePeriod> irregularAvailablePeriodList; 460 } 461 462 public static class NormalCouponUsageRule { 463 @SerializedName("threshold") 464 public Long threshold; 465 466 @SerializedName("discount_amount") 467 public Long discountAmount; 468 } 469 470 public static class DiscountCouponUsageRule { 471 @SerializedName("threshold") 472 public Long threshold; 473 474 @SerializedName("percent_off") 475 public Long percentOff; 476 } 477 478 public static class ExchangeCouponUsageRule { 479 @SerializedName("threshold") 480 public Long threshold; 481 482 @SerializedName("exchange_price") 483 public Long exchangePrice; 484 } 485 486 public static class SequentialCouponAvailablePeriod { 487 @SerializedName("available_begin_time") 488 public String availableBeginTime; 489 490 @SerializedName("available_end_time") 491 public String availableEndTime; 492 493 @SerializedName("wait_days_after_receive") 494 public Long waitDaysAfterReceive; 495 496 @SerializedName("weekly_available_period") 497 public FixedWeekPeriod weeklyAvailablePeriod; 498 499 @SerializedName("irregular_available_period_list") 500 public List<TimePeriod> irregularAvailablePeriodList; 501 } 502 503 public enum CouponUsageMethod { 504 @SerializedName("OFFLINE") 505 OFFLINE, 506 @SerializedName("MINI_PROGRAM") 507 MINI_PROGRAM, 508 @SerializedName("APP") 509 APP, 510 @SerializedName("PAYMENT_CODE") 511 PAYMENT_CODE 512 } 513 514 public static class CouponAvailableStoreInfo { 515 @SerializedName("description") 516 public String description; 517 518 @SerializedName("mini_program_appid") 519 public String miniProgramAppid; 520 521 @SerializedName("mini_program_path") 522 public String miniProgramPath; 523 } 524 525 public enum CouponCodeDisplayMode { 526 @SerializedName("INVISIBLE") 527 INVISIBLE, 528 @SerializedName("BARCODE") 529 BARCODE, 530 @SerializedName("QRCODE") 531 QRCODE 532 } 533 534 public static class EntranceMiniProgram { 535 @SerializedName("appid") 536 public String appid; 537 538 @SerializedName("path") 539 public String path; 540 541 @SerializedName("entrance_wording") 542 public String entranceWording; 543 544 @SerializedName("guidance_wording") 545 public String guidanceWording; 546 } 547 548 public static class EntranceOfficialAccount { 549 @SerializedName("appid") 550 public String appid; 551 } 552 553 public static class EntranceFinder { 554 @SerializedName("finder_id") 555 public String finderId; 556 557 @SerializedName("finder_video_id") 558 public String finderVideoId; 559 560 @SerializedName("finder_video_cover_image_url") 561 public String finderVideoCoverImageUrl; 562 } 563 564 public static class FixedWeekPeriod { 565 @SerializedName("day_list") 566 public List<WeekEnum> dayList; 567 568 @SerializedName("day_period_list") 569 public List<PeriodOfTheDay> dayPeriodList; 570 } 571 572 public static class TimePeriod { 573 @SerializedName("begin_time") 574 public String beginTime; 575 576 @SerializedName("end_time") 577 public String endTime; 578 } 579 580 public enum WeekEnum { 581 @SerializedName("MONDAY") 582 MONDAY, 583 @SerializedName("TUESDAY") 584 TUESDAY, 585 @SerializedName("WEDNESDAY") 586 WEDNESDAY, 587 @SerializedName("THURSDAY") 588 THURSDAY, 589 @SerializedName("FRIDAY") 590 FRIDAY, 591 @SerializedName("SATURDAY") 592 SATURDAY, 593 @SerializedName("SUNDAY") 594 SUNDAY 595 } 596 597 public static class PeriodOfTheDay { 598 @SerializedName("begin_time") 599 public Long beginTime; 600 601 @SerializedName("end_time") 602 public Long endTime; 603 } 604 605} 606
需配合微信支付工具库 wxpay_utility 使用,请参考Go
1package main 2 3import ( 4 "bytes" 5 "demo/wxpay_brand_utility" // 引用微信支付工具库,参考 https://pay.weixin.qq.com/doc/brand/4015826866 6 "encoding/json" 7 "fmt" 8 "net/http" 9 "net/url" 10 "strings" 11 "time" 12) 13 14func main() { 15 // TODO: 请准备商户开发必要参数,参考:https://pay.weixin.qq.com/doc/brand/4015415289 16 config, err := wxpay_brand_utility.CreateBrandConfig( 17 "xxxxxxxx", // 品牌ID,是由微信支付系统生成并分配给每个品牌方的唯一标识符,品牌ID获取方式参考 https://pay.weixin.qq.com/doc/brand/4015415289 18 "1DDE55AD98Exxxxxxxxxx", // 品牌API证书序列号,如何获取请参考 https://pay.weixin.qq.com/doc/brand/4015407570 19 "/path/to/apiclient_key.pem", // 品牌API证书私钥文件路径,本地文件路径 20 "PUB_KEY_ID_xxxxxxxxxxxxx", // 微信支付公钥ID,如何获取请参考 https://pay.weixin.qq.com/doc/brand/4015453439 21 "/path/to/wxp_pub.pem", // 微信支付公钥文件路径,本地文件路径 22 ) 23 if err != nil { 24 fmt.Println(err) 25 return 26 } 27 28 request := &CreateStockRequest{ 29 ProductCouponId: wxpay_brand_utility.String("200000001"), 30 OutRequestNo: wxpay_brand_utility.String("34657_20250101_123456"), 31 Stock: &StockForCreate{ 32 Remark: wxpay_brand_utility.String("满减券"), 33 CouponCodeMode: COUPONCODEMODE_UPLOAD.Ptr(), 34 StockSendRule: &StockSendRule{ 35 MaxCount: wxpay_brand_utility.Int64(10000000), 36 MaxCountPerDay: wxpay_brand_utility.Int64(10000), 37 MaxCountPerUser: wxpay_brand_utility.Int64(1), 38 }, 39 SingleUsageRule: &SingleUsageRule{ 40 CouponAvailablePeriod: &SingleCouponAvailablePeriod{ 41 AvailableBeginTime: wxpay_brand_utility.String("2025-01-01T00:00:00+08:00"), 42 AvailableEndTime: wxpay_brand_utility.String("2025-10-01T00:00:00+08:00"), 43 AvailableDays: wxpay_brand_utility.Int64(10), 44 WaitDaysAfterReceive: wxpay_brand_utility.Int64(1), 45 WeeklyAvailablePeriod: &FixedWeekPeriod{ 46 DayList: []WeekEnum{WEEKENUM_MONDAY}, 47 DayPeriodList: []PeriodOfTheDay{PeriodOfTheDay{ 48 BeginTime: wxpay_brand_utility.Int64(60), 49 EndTime: wxpay_brand_utility.Int64(86399), 50 }}, 51 }, 52 IrregularAvailablePeriodList: []TimePeriod{TimePeriod{ 53 BeginTime: wxpay_brand_utility.String("2025-01-01T00:00:00+08:00"), 54 EndTime: wxpay_brand_utility.String("2025-10-01T00:00:00+08:00"), 55 }}, 56 }, 57 NormalCoupon: &NormalCouponUsageRule{ 58 Threshold: wxpay_brand_utility.Int64(10000), 59 DiscountAmount: wxpay_brand_utility.Int64(100), 60 }, 61 DiscountCoupon: &DiscountCouponUsageRule{ 62 Threshold: wxpay_brand_utility.Int64(10000), 63 PercentOff: wxpay_brand_utility.Int64(30), 64 }, 65 ExchangeCoupon: &ExchangeCouponUsageRule{ 66 Threshold: wxpay_brand_utility.Int64(10000), 67 ExchangePrice: wxpay_brand_utility.Int64(100), 68 }, 69 }, 70 SequentialUsageRule: &SequentialUsageRule{ 71 CouponAvailablePeriod: &SequentialCouponAvailablePeriod{ 72 AvailableBeginTime: wxpay_brand_utility.String("2025-01-01T00:00:00+08:00"), 73 AvailableEndTime: wxpay_brand_utility.String("2025-10-01T00:00:00+08:00"), 74 WaitDaysAfterReceive: wxpay_brand_utility.Int64(1), 75 WeeklyAvailablePeriod: &FixedWeekPeriod{ 76 DayList: []WeekEnum{WEEKENUM_MONDAY}, 77 DayPeriodList: []PeriodOfTheDay{PeriodOfTheDay{ 78 BeginTime: wxpay_brand_utility.Int64(60), 79 EndTime: wxpay_brand_utility.Int64(86399), 80 }}, 81 }, 82 IrregularAvailablePeriodList: []TimePeriod{TimePeriod{ 83 BeginTime: wxpay_brand_utility.String("2025-01-01T00:00:00+08:00"), 84 EndTime: wxpay_brand_utility.String("2025-10-01T00:00:00+08:00"), 85 }}, 86 }, 87 NormalCouponList: []NormalCouponUsageRule{NormalCouponUsageRule{ 88 Threshold: wxpay_brand_utility.Int64(10000), 89 DiscountAmount: wxpay_brand_utility.Int64(100), 90 }}, 91 DiscountCouponList: []DiscountCouponUsageRule{DiscountCouponUsageRule{ 92 Threshold: wxpay_brand_utility.Int64(10000), 93 PercentOff: wxpay_brand_utility.Int64(30), 94 }}, 95 ExchangeCouponList: []ExchangeCouponUsageRule{ExchangeCouponUsageRule{ 96 Threshold: wxpay_brand_utility.Int64(10000), 97 ExchangePrice: wxpay_brand_utility.Int64(100), 98 }}, 99 SpecialFirst: wxpay_brand_utility.Bool(false), 100 }, 101 UsageRuleDisplayInfo: &UsageRuleDisplayInfo{ 102 CouponUsageMethodList: []CouponUsageMethod{COUPONUSAGEMETHOD_OFFLINE}, 103 MiniProgramAppid: wxpay_brand_utility.String("wx1234567890"), 104 MiniProgramPath: wxpay_brand_utility.String("/pages/index/product"), 105 AppPath: wxpay_brand_utility.String("https://www.example.com/jump-to-app"), 106 UsageDescription: wxpay_brand_utility.String("全场可用"), 107 CouponAvailableStoreInfo: &CouponAvailableStoreInfo{ 108 Description: wxpay_brand_utility.String("可在上海市区的所有门店使用,详细列表参考小程序内信息为准"), 109 MiniProgramAppid: wxpay_brand_utility.String("wx1234567890"), 110 MiniProgramPath: wxpay_brand_utility.String("/pages/index/store-list"), 111 }, 112 }, 113 CouponDisplayInfo: &CouponDisplayInfo{ 114 CodeDisplayMode: COUPONCODEDISPLAYMODE_QRCODE.Ptr(), 115 BackgroundColor: wxpay_brand_utility.String("Color010"), 116 EntranceMiniProgram: &EntranceMiniProgram{ 117 Appid: wxpay_brand_utility.String("wx1234567890"), 118 Path: wxpay_brand_utility.String("/pages/index/product"), 119 EntranceWording: wxpay_brand_utility.String("欢迎选购"), 120 GuidanceWording: wxpay_brand_utility.String("获取更多优惠"), 121 }, 122 EntranceOfficialAccount: &EntranceOfficialAccount{ 123 Appid: wxpay_brand_utility.String("wx1234567890"), 124 }, 125 EntranceFinder: &EntranceFinder{ 126 FinderId: wxpay_brand_utility.String("gh_12345678"), 127 FinderVideoId: wxpay_brand_utility.String("UDFsdf24df34dD456Hdf34"), 128 FinderVideoCoverImageUrl: wxpay_brand_utility.String("https://wxpaylogo.qpic.cn/wxpaylogo/xxxxx/xxx"), 129 }, 130 }, 131 NotifyConfig: &NotifyConfig{ 132 NotifyAppid: wxpay_brand_utility.String("wx4fd12345678"), 133 }, 134 StoreScope: STOCKSTORESCOPE_SPECIFIC.Ptr(), 135 }, 136 } 137 138 response, err := CreateStock(config, request) 139 if err != nil { 140 fmt.Printf("请求失败: %+v\n", err) 141 // TODO: 请求失败,根据状态码执行不同的处理 142 return 143 } 144 145 // TODO: 请求成功,继续业务逻辑 146 fmt.Printf("请求成功: %+v\n", response) 147} 148 149func CreateStock(config *wxpay_brand_utility.BrandConfig, request *CreateStockRequest) (response *StockEntity, err error) { 150 const ( 151 host = "https://api.mch.weixin.qq.com" 152 method = "POST" 153 path = "/brand/marketing/product-coupon/product-coupons/{product_coupon_id}/stocks" 154 ) 155 156 reqUrl, err := url.Parse(fmt.Sprintf("%s%s", host, path)) 157 if err != nil { 158 return nil, err 159 } 160 reqUrl.Path = strings.Replace(reqUrl.Path, "{product_coupon_id}", url.PathEscape(*request.ProductCouponId), -1) 161 reqBody, err := json.Marshal(request) 162 if err != nil { 163 return nil, err 164 } 165 httpRequest, err := http.NewRequest(method, reqUrl.String(), bytes.NewReader(reqBody)) 166 if err != nil { 167 return nil, err 168 } 169 httpRequest.Header.Set("Accept", "application/json") 170 httpRequest.Header.Set("Wechatpay-Serial", config.WechatPayPublicKeyId()) 171 httpRequest.Header.Set("Content-Type", "application/json") 172 authorization, err := wxpay_brand_utility.BuildAuthorization(config.BrandId(), config.CertificateSerialNo(), config.PrivateKey(), method, reqUrl.RequestURI(), reqBody) 173 if err != nil { 174 return nil, err 175 } 176 httpRequest.Header.Set("Authorization", authorization) 177 178 client := &http.Client{} 179 httpResponse, err := client.Do(httpRequest) 180 if err != nil { 181 return nil, err 182 } 183 respBody, err := wxpay_brand_utility.ExtractResponseBody(httpResponse) 184 if err != nil { 185 return nil, err 186 } 187 if httpResponse.StatusCode >= 200 && httpResponse.StatusCode < 300 { 188 // 2XX 成功,验证应答签名 189 err = wxpay_brand_utility.ValidateResponse( 190 config.WechatPayPublicKeyId(), 191 config.WechatPayPublicKey(), 192 &httpResponse.Header, 193 respBody, 194 ) 195 if err != nil { 196 return nil, err 197 } 198 response := &StockEntity{} 199 if err := json.Unmarshal(respBody, response); err != nil { 200 return nil, err 201 } 202 203 return response, nil 204 } else { 205 return nil, wxpay_brand_utility.NewApiException( 206 httpResponse.StatusCode, 207 httpResponse.Header, 208 respBody, 209 ) 210 } 211} 212 213type CreateStockRequest struct { 214 OutRequestNo *string `json:"out_request_no,omitempty"` 215 ProductCouponId *string `json:"product_coupon_id,omitempty"` 216 Stock *StockForCreate `json:"stock,omitempty"` 217} 218 219func (o *CreateStockRequest) MarshalJSON() ([]byte, error) { 220 type Alias CreateStockRequest 221 a := &struct { 222 ProductCouponId *string `json:"product_coupon_id,omitempty"` 223 *Alias 224 }{ 225 // 序列化时移除非 Body 字段 226 ProductCouponId: nil, 227 Alias: (*Alias)(o), 228 } 229 return json.Marshal(a) 230} 231 232type StockEntity struct { 233 ProductCouponId *string `json:"product_coupon_id,omitempty"` 234 StockId *string `json:"stock_id,omitempty"` 235 Remark *string `json:"remark,omitempty"` 236 CouponCodeMode *CouponCodeMode `json:"coupon_code_mode,omitempty"` 237 CouponCodeCountInfo *CouponCodeCountInfo `json:"coupon_code_count_info,omitempty"` 238 StockSendRule *StockSendRule `json:"stock_send_rule,omitempty"` 239 SingleUsageRule *SingleUsageRule `json:"single_usage_rule,omitempty"` 240 SequentialUsageRule *SequentialUsageRule `json:"sequential_usage_rule,omitempty"` 241 UsageRuleDisplayInfo *UsageRuleDisplayInfo `json:"usage_rule_display_info,omitempty"` 242 CouponDisplayInfo *CouponDisplayInfo `json:"coupon_display_info,omitempty"` 243 NotifyConfig *NotifyConfig `json:"notify_config,omitempty"` 244 StoreScope *StockStoreScope `json:"store_scope,omitempty"` 245 SentCountInfo *StockSentCountInfo `json:"sent_count_info,omitempty"` 246 State *StockState `json:"state,omitempty"` 247 DeactivateRequestNo *string `json:"deactivate_request_no,omitempty"` 248 DeactivateTime *time.Time `json:"deactivate_time,omitempty"` 249 DeactivateReason *string `json:"deactivate_reason,omitempty"` 250} 251 252type StockForCreate struct { 253 Remark *string `json:"remark,omitempty"` 254 CouponCodeMode *CouponCodeMode `json:"coupon_code_mode,omitempty"` 255 StockSendRule *StockSendRule `json:"stock_send_rule,omitempty"` 256 SingleUsageRule *SingleUsageRule `json:"single_usage_rule,omitempty"` 257 SequentialUsageRule *SequentialUsageRule `json:"sequential_usage_rule,omitempty"` 258 UsageRuleDisplayInfo *UsageRuleDisplayInfo `json:"usage_rule_display_info,omitempty"` 259 CouponDisplayInfo *CouponDisplayInfo `json:"coupon_display_info,omitempty"` 260 NotifyConfig *NotifyConfig `json:"notify_config,omitempty"` 261 StoreScope *StockStoreScope `json:"store_scope,omitempty"` 262} 263 264type CouponCodeMode string 265 266func (e CouponCodeMode) Ptr() *CouponCodeMode { 267 return &e 268} 269 270const ( 271 COUPONCODEMODE_WECHATPAY CouponCodeMode = "WECHATPAY" 272 COUPONCODEMODE_UPLOAD CouponCodeMode = "UPLOAD" 273 COUPONCODEMODE_API_ASSIGN CouponCodeMode = "API_ASSIGN" 274) 275 276type CouponCodeCountInfo struct { 277 TotalCount *int64 `json:"total_count,omitempty"` 278 AvailableCount *int64 `json:"available_count,omitempty"` 279} 280 281type StockSendRule struct { 282 MaxCount *int64 `json:"max_count,omitempty"` 283 MaxCountPerDay *int64 `json:"max_count_per_day,omitempty"` 284 MaxCountPerUser *int64 `json:"max_count_per_user,omitempty"` 285} 286 287type SingleUsageRule struct { 288 CouponAvailablePeriod *SingleCouponAvailablePeriod `json:"coupon_available_period,omitempty"` 289 NormalCoupon *NormalCouponUsageRule `json:"normal_coupon,omitempty"` 290 DiscountCoupon *DiscountCouponUsageRule `json:"discount_coupon,omitempty"` 291 ExchangeCoupon *ExchangeCouponUsageRule `json:"exchange_coupon,omitempty"` 292} 293 294type SequentialUsageRule struct { 295 CouponAvailablePeriod *SequentialCouponAvailablePeriod `json:"coupon_available_period,omitempty"` 296 NormalCouponList []NormalCouponUsageRule `json:"normal_coupon_list,omitempty"` 297 DiscountCouponList []DiscountCouponUsageRule `json:"discount_coupon_list,omitempty"` 298 ExchangeCouponList []ExchangeCouponUsageRule `json:"exchange_coupon_list,omitempty"` 299 SpecialFirst *bool `json:"special_first,omitempty"` 300} 301 302type UsageRuleDisplayInfo struct { 303 CouponUsageMethodList []CouponUsageMethod `json:"coupon_usage_method_list,omitempty"` 304 MiniProgramAppid *string `json:"mini_program_appid,omitempty"` 305 MiniProgramPath *string `json:"mini_program_path,omitempty"` 306 AppPath *string `json:"app_path,omitempty"` 307 UsageDescription *string `json:"usage_description,omitempty"` 308 CouponAvailableStoreInfo *CouponAvailableStoreInfo `json:"coupon_available_store_info,omitempty"` 309} 310 311type CouponDisplayInfo struct { 312 CodeDisplayMode *CouponCodeDisplayMode `json:"code_display_mode,omitempty"` 313 BackgroundColor *string `json:"background_color,omitempty"` 314 EntranceMiniProgram *EntranceMiniProgram `json:"entrance_mini_program,omitempty"` 315 EntranceOfficialAccount *EntranceOfficialAccount `json:"entrance_official_account,omitempty"` 316 EntranceFinder *EntranceFinder `json:"entrance_finder,omitempty"` 317} 318 319type NotifyConfig struct { 320 NotifyAppid *string `json:"notify_appid,omitempty"` 321} 322 323type StockStoreScope string 324 325func (e StockStoreScope) Ptr() *StockStoreScope { 326 return &e 327} 328 329const ( 330 STOCKSTORESCOPE_NONE StockStoreScope = "NONE" 331 STOCKSTORESCOPE_ALL StockStoreScope = "ALL" 332 STOCKSTORESCOPE_SPECIFIC StockStoreScope = "SPECIFIC" 333) 334 335type StockSentCountInfo struct { 336 TotalCount *int64 `json:"total_count,omitempty"` 337 TodayCount *int64 `json:"today_count,omitempty"` 338} 339 340type StockState string 341 342func (e StockState) Ptr() *StockState { 343 return &e 344} 345 346const ( 347 STOCKSTATE_AUDITING StockState = "AUDITING" 348 STOCKSTATE_SENDING StockState = "SENDING" 349 STOCKSTATE_PAUSED StockState = "PAUSED" 350 STOCKSTATE_STOPPED StockState = "STOPPED" 351 STOCKSTATE_DEACTIVATED StockState = "DEACTIVATED" 352) 353 354type SingleCouponAvailablePeriod struct { 355 AvailableBeginTime *string `json:"available_begin_time,omitempty"` 356 AvailableEndTime *string `json:"available_end_time,omitempty"` 357 AvailableDays *int64 `json:"available_days,omitempty"` 358 WaitDaysAfterReceive *int64 `json:"wait_days_after_receive,omitempty"` 359 WeeklyAvailablePeriod *FixedWeekPeriod `json:"weekly_available_period,omitempty"` 360 IrregularAvailablePeriodList []TimePeriod `json:"irregular_available_period_list,omitempty"` 361} 362 363type NormalCouponUsageRule struct { 364 Threshold *int64 `json:"threshold,omitempty"` 365 DiscountAmount *int64 `json:"discount_amount,omitempty"` 366} 367 368type DiscountCouponUsageRule struct { 369 Threshold *int64 `json:"threshold,omitempty"` 370 PercentOff *int64 `json:"percent_off,omitempty"` 371} 372 373type ExchangeCouponUsageRule struct { 374 Threshold *int64 `json:"threshold,omitempty"` 375 ExchangePrice *int64 `json:"exchange_price,omitempty"` 376} 377 378type SequentialCouponAvailablePeriod struct { 379 AvailableBeginTime *string `json:"available_begin_time,omitempty"` 380 AvailableEndTime *string `json:"available_end_time,omitempty"` 381 WaitDaysAfterReceive *int64 `json:"wait_days_after_receive,omitempty"` 382 WeeklyAvailablePeriod *FixedWeekPeriod `json:"weekly_available_period,omitempty"` 383 IrregularAvailablePeriodList []TimePeriod `json:"irregular_available_period_list,omitempty"` 384} 385 386type CouponUsageMethod string 387 388func (e CouponUsageMethod) Ptr() *CouponUsageMethod { 389 return &e 390} 391 392const ( 393 COUPONUSAGEMETHOD_OFFLINE CouponUsageMethod = "OFFLINE" 394 COUPONUSAGEMETHOD_MINI_PROGRAM CouponUsageMethod = "MINI_PROGRAM" 395 COUPONUSAGEMETHOD_APP CouponUsageMethod = "APP" 396 COUPONUSAGEMETHOD_PAYMENT_CODE CouponUsageMethod = "PAYMENT_CODE" 397) 398 399type CouponAvailableStoreInfo struct { 400 Description *string `json:"description,omitempty"` 401 MiniProgramAppid *string `json:"mini_program_appid,omitempty"` 402 MiniProgramPath *string `json:"mini_program_path,omitempty"` 403} 404 405type CouponCodeDisplayMode string 406 407func (e CouponCodeDisplayMode) Ptr() *CouponCodeDisplayMode { 408 return &e 409} 410 411const ( 412 COUPONCODEDISPLAYMODE_INVISIBLE CouponCodeDisplayMode = "INVISIBLE" 413 COUPONCODEDISPLAYMODE_BARCODE CouponCodeDisplayMode = "BARCODE" 414 COUPONCODEDISPLAYMODE_QRCODE CouponCodeDisplayMode = "QRCODE" 415) 416 417type EntranceMiniProgram struct { 418 Appid *string `json:"appid,omitempty"` 419 Path *string `json:"path,omitempty"` 420 EntranceWording *string `json:"entrance_wording,omitempty"` 421 GuidanceWording *string `json:"guidance_wording,omitempty"` 422} 423 424type EntranceOfficialAccount struct { 425 Appid *string `json:"appid,omitempty"` 426} 427 428type EntranceFinder struct { 429 FinderId *string `json:"finder_id,omitempty"` 430 FinderVideoId *string `json:"finder_video_id,omitempty"` 431 FinderVideoCoverImageUrl *string `json:"finder_video_cover_image_url,omitempty"` 432} 433 434type FixedWeekPeriod struct { 435 DayList []WeekEnum `json:"day_list,omitempty"` 436 DayPeriodList []PeriodOfTheDay `json:"day_period_list,omitempty"` 437} 438 439type TimePeriod struct { 440 BeginTime *string `json:"begin_time,omitempty"` 441 EndTime *string `json:"end_time,omitempty"` 442} 443 444type WeekEnum string 445 446func (e WeekEnum) Ptr() *WeekEnum { 447 return &e 448} 449 450const ( 451 WEEKENUM_MONDAY WeekEnum = "MONDAY" 452 WEEKENUM_TUESDAY WeekEnum = "TUESDAY" 453 WEEKENUM_WEDNESDAY WeekEnum = "WEDNESDAY" 454 WEEKENUM_THURSDAY WeekEnum = "THURSDAY" 455 WEEKENUM_FRIDAY WeekEnum = "FRIDAY" 456 WEEKENUM_SATURDAY WeekEnum = "SATURDAY" 457 WEEKENUM_SUNDAY WeekEnum = "SUNDAY" 458) 459 460type PeriodOfTheDay struct { 461 BeginTime *int64 `json:"begin_time,omitempty"` 462 EndTime *int64 `json:"end_time,omitempty"` 463} 464
应答参数
200 OK
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不足时可能影响发券,品牌应及时补充API_ASSIGN: 品牌方自行指定,品牌方通过发券API自行发券时指定,微信支付系统不再进行自动分配。特别注意:这种模式的商品批次只可由品牌方自行发券,无法在摇一摇有优惠等微信支付渠道投放
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 次。 |
single_usage_rule 选填 object
【单券使用规则】 当且仅当 usage_mode 为 SINGLE 时提供,其他场景不提供
| 属性 | |||||||||||||||||||||||||||||
coupon_available_period 必填 object 【券可核销时间】 确定用户领券后在什么时间段内可以核销
normal_coupon 选填 object 【满减券使用规则】 当且仅当
discount_coupon 选填 object 【折扣券使用规则】 当且仅当
exchange_coupon 选填 object 【兑换券使用规则】 当且仅当
|
sequential_usage_rule 选填 object
【多次优惠使用规则】 当且仅当 usage_mode 为 SEQUENTIAL 时提供,其他场景不提供
| 属性 | |||||||||||||||||||||||||||||
coupon_available_period 必填 object 【多次优惠可核销时间】 确定用户领取多次优惠后在什么时间段内可以核销,多次优惠可核销时间不会超过多次优惠有效天数(多次优惠商品券中配置的
normal_coupon_list 选填 array[object] 【满减券使用规则】 当且仅当
discount_coupon_list 选填 array[object] 【折扣券使用规则】 当且仅当
exchange_coupon_list 选填 array[object] 【兑换券使用规则】 当且仅当
special_first 选填 boolean 【多次优惠是否提供首笔特惠】 默认情况下为 当此字段设置为 |
usage_rule_display_info 必填 object
【券使用规则展示信息】 券使用规则展示信息
| 属性 | |||||
coupon_usage_method_list 必填 array[string] 【券使用方式列表】 可以配置多种使用方式 可选取值
mini_program_appid 选填 string 【小程序AppID】 品牌方小程序AppID,可在微信公众平台查看,该小程序与品牌存在绑定关系。 在 mini_program_path 选填 string 【小程序跳转路径】 品牌方小程序内部跳转路径。 在 app_path 选填 string 【APP跳转路径】 品牌方APP跳转路径,在 usage_description 必填 string(1000) 【券使用说明】 用于说明详细的券规则,长度不超过1000个UTF-8字符 coupon_available_store_info 选填 object 【券可用门店信息】 用于描述全部可用门店信息,可配置小程序跳转地址进行展示
|
coupon_display_info 必填 object
【用户商品券展示信息】 用户商品券在卡包中的展示详情,包括引导用户的自定义入口
| 属性 | |||||||||||||
code_display_mode 必填 string 【用户商品券Code展示模式】 决定用户商品券Code在卡包中的展示形态 可选取值
background_color 选填 string 【背景颜色】 券的背景颜色,可设置10种颜色,色值请参考下方说明。颜色取值为颜色图中的颜色名称,不填默认为
entrance_mini_program 选填 object 【小程序入口】 展示跳转小程序的入口
entrance_official_account 选填 object 【公众号入口】 展示跳转公众号的入口
entrance_finder 选填 object 【视频号入口】 展示跳转视频号的入口
|
notify_config 必填 object
【事件通知配置】 发生券相关事件时,微信支付会向品牌方发送通知,需要提供通知相关配置
| 属性 | |
notify_appid 必填 string 【事件通知AppID】 品牌方小程序或公众号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
【失效请求单号】 当且仅当 state 为 DEACTIVATED 时提供,返回品牌方调用失效接口时传入的请求流水号
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
【失效原因】 当且仅当 state 为 DEACTIVATED 时提供,返回品牌方调用失效商品券批次接口时传入的失效原因
应答示例
200 OK
1{ 2 "product_coupon_id" : "200000001", 3 "stock_id" : "123456789", 4 "remark" : "满减券", 5 "coupon_code_mode" : "UPLOAD", 6 "coupon_code_count_info" : { 7 "total_count" : 10000, 8 "available_count" : 999 9 }, 10 "stock_send_rule" : { 11 "max_count" : 10000000, 12 "max_count_per_day" : 10000, 13 "max_count_per_user" : 1 14 }, 15 "single_usage_rule" : { 16 "coupon_available_period" : { 17 "available_begin_time" : "2025-01-01T00:00:00+08:00", 18 "available_end_time" : "2025-10-01T00:00:00+08:00", 19 "available_days" : 10, 20 "wait_days_after_receive" : 1, 21 "weekly_available_period" : { 22 "day_list" : [ 23 "MONDAY" 24 ], 25 "day_period_list" : [ 26 { 27 "begin_time" : 60, 28 "end_time" : 86399 29 } 30 ] 31 }, 32 "irregular_available_period_list" : [ 33 { 34 "begin_time" : "2025-01-01T00:00:00+08:00", 35 "end_time" : "2025-10-01T00:00:00+08:00" 36 } 37 ] 38 }, 39 "normal_coupon" : { 40 "threshold" : 10000, 41 "discount_amount" : 100 42 }, 43 "discount_coupon" : { 44 "threshold" : 10000, 45 "percent_off" : 30 46 }, 47 "exchange_coupon" : { 48 "threshold" : 10000, 49 "exchange_price" : 100 50 } 51 }, 52 "sequential_usage_rule" : { 53 "coupon_available_period" : { 54 "available_begin_time" : "2025-01-01T00:00:00+08:00", 55 "available_end_time" : "2025-10-01T00:00:00+08:00", 56 "wait_days_after_receive" : 1, 57 "weekly_available_period" : { 58 "day_list" : [ 59 "MONDAY" 60 ], 61 "day_period_list" : [ 62 { 63 "begin_time" : 60, 64 "end_time" : 86399 65 } 66 ] 67 }, 68 "irregular_available_period_list" : [ 69 { 70 "begin_time" : "2025-01-01T00:00:00+08:00", 71 "end_time" : "2025-10-01T00:00:00+08:00" 72 } 73 ] 74 }, 75 "normal_coupon_list" : [ 76 { 77 "threshold" : 10000, 78 "discount_amount" : 100 79 } 80 ], 81 "discount_coupon_list" : [ 82 { 83 "threshold" : 10000, 84 "percent_off" : 30 85 } 86 ], 87 "exchange_coupon_list" : [ 88 { 89 "threshold" : 10000, 90 "exchange_price" : 100 91 } 92 ], 93 "special_first" : false 94 }, 95 "usage_rule_display_info" : { 96 "coupon_usage_method_list" : [ 97 "MINI_PROGRAM" 98 ], 99 "mini_program_appid" : "wx1234567890", 100 "mini_program_path" : "/pages/index/product", 101 "app_path" : "https://www.example.com/jump-to-app", 102 "usage_description" : "全场可用", 103 "coupon_available_store_info" : { 104 "description" : "可在上海市区的所有门店使用,详细列表参考小程序内信息为准", 105 "mini_program_appid" : "wx1234567890", 106 "mini_program_path" : "/pages/index/store-list" 107 } 108 }, 109 "coupon_display_info" : { 110 "code_display_mode" : "QRCODE", 111 "background_color" : "Color010", 112 "entrance_mini_program" : { 113 "appid" : "wx1234567890", 114 "path" : "/pages/index/product", 115 "entrance_wording" : "欢迎选购", 116 "guidance_wording" : "获取更多优惠" 117 }, 118 "entrance_official_account" : { 119 "appid" : "wx1234567890" 120 }, 121 "entrance_finder" : { 122 "finder_id" : "gh_12345678", 123 "finder_video_id" : "UDFsdf24df34dD456Hdf34", 124 "finder_video_cover_image_url" : "https://wxpaylogo.qpic.cn/wxpaylogo/xxxxx/xxx" 125 } 126 }, 127 "notify_config" : { 128 "notify_appid" : "wx4fd12345678" 129 }, 130 "store_scope" : "SPECIFIC", 131 "sent_count_info" : { 132 "total_count" : 100, 133 "today_count" : 10 134 }, 135 "state" : "SENDING", 136 "deactivate_request_no" : "1002600620019090123143254436", 137 "deactivate_time" : "2025-01-01T00:00+08:00", 138 "deactivate_reason" : "批次信息有误,重新创建" 139} 140
错误码
以下是本接口返回的错误码列表。详细错误码规则,请参考微信支付接口规则-错误码和错误提示
状态码 | 错误码 | 描述 | 解决方案 |
|---|---|---|---|
400 | PARAM_ERROR | 参数错误 | 请根据错误提示正确传入参数 |
400 | INVALID_REQUEST | HTTP 请求不符合微信支付 APIv3 接口规则 | 请参阅 接口规则 |
401 | SIGN_ERROR | 验证不通过 | 请参阅 签名常见问题 |
500 | SYSTEM_ERROR | 系统异常,请稍后重试 | 请稍后重试 |
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 | 商品券支持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 |


