查询商品券指定批次
更新时间：2025.11.07品牌方可以通过该接口查询某个商品券批次的详情。
前置条件：已创建商品券批次
频率限制：20/s
接口说明
支持商户：【品牌商户】
请求方式：【GET】/brand/marketing/product-coupon/product-coupons/{product_coupon_id}/stocks/{stock_id}
请求域名：【主域名】https://api.mch.weixin.qq.com 使用该域名将访问就近的接入点
【备域名】https://api2.mch.weixin.qq.com 使用该域名将访问异地的接入点 ，指引点击查看
请求参数
Header HTTP头参数
Authorization 必填 string
请参考签名认证生成认证信息
Accept 必填 string
请设置为application/json
Wechatpay-Serial 必填 string
【微信支付公钥ID】 请传入brand_id对应的微信支付公钥ID，接口将会校验两者的关联关系，参考微信支付公钥产品简介及使用说明获取微信支付公钥ID和相关的介绍。以下两种场景将使用到微信支付公钥： 1、接收到接口的返回内容，需要使用微信支付公钥进行验签； 2、调用含有敏感信息参数（如姓名、身份证号码）的接口时，需要使用微信支付公钥加密敏感信息后再传输参数，加密指引请参考微信支付公钥加密敏感信息指引。
path 路径参数
product_coupon_id 必填 string
【商品券ID】 商品券的唯一标识，创建商品券时由微信支付生成
stock_id 必填 string
【批次ID】 商品券批次的唯一标识，商品券批次创建时由微信支付生成（可使用【创建商品券API】或【添加商品券批次API】创建），请确保该批次属于 product_coupon_id 对应的商品券
请求示例
GET
查询单券批次
1curl -X GET \ 2 https://api.mch.weixin.qq.com/brand/marketing/product-coupon/product-coupons/1000000013/stocks/1000000013001 \ 3 -H "Authorization: WECHATPAY-BRAND-SHA256-RSA2048 brand_id=\"XXXX\",..." \ 4 -H "Accept: application/json" \ 5 -H "Wechatpay-Serial: PUB_KEY_ID_XXXX" 6
查询多次优惠批次
1curl -X GET \ 2 https://api.mch.weixin.qq.com/brand/marketing/product-coupon/product-coupons/1000000014/stocks/1000000014002 \ 3 -H "Authorization: WECHATPAY-BRAND-SHA256-RSA2048 brand_id=\"XXXX\",..." \ 4 -H "Accept: application/json" \ 5 -H "Wechatpay-Serial: PUB_KEY_ID_XXXX" 6
需配合微信支付工具库 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 GetStock { 26 private static String HOST = "https://api.mch.weixin.qq.com"; 27 private static String METHOD = "GET"; 28 private static String PATH = "/brand/marketing/product-coupon/product-coupons/{product_coupon_id}/stocks/{stock_id}"; 29 30 public static void main(String[] args) { 31 // TODO: 请准备商户开发必要参数，参考：https://pay.weixin.qq.com/doc/brand/4015415289 32 GetStock client = new GetStock( 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 GetStockRequest request = new GetStockRequest(); 41 request.productCouponId = "1000000013"; 42 request.stockId = "1000000013001"; 43 try { 44 StockEntity response = client.run(request); 45 // TODO: 请求成功，继续业务逻辑 46 System.out.println(response); 47 } catch (WXPayBrandUtility.ApiException e) { 48 // TODO: 请求失败，根据状态码执行不同的逻辑 49 e.printStackTrace(); 50 } 51 } 52 53 public StockEntity run(GetStockRequest request) { 54 String uri = PATH; 55 uri = uri.replace("{product_coupon_id}", WXPayBrandUtility.urlEncode(request.productCouponId)); 56 uri = uri.replace("{stock_id}", WXPayBrandUtility.urlEncode(request.stockId)); 57 58 Request.Builder reqBuilder = new Request.Builder().url(HOST + uri); 59 reqBuilder.addHeader("Accept", "application/json"); 60 reqBuilder.addHeader("Wechatpay-Serial", wechatPayPublicKeyId); 61 reqBuilder.addHeader("Authorization", WXPayBrandUtility.buildAuthorization(brand_id, certificateSerialNo, privateKey, METHOD, uri, null)); 62 reqBuilder.method(METHOD, null); 63 Request httpRequest = reqBuilder.build(); 64 65 // 发送HTTP请求 66 OkHttpClient client = new OkHttpClient.Builder().build(); 67 try (Response httpResponse = client.newCall(httpRequest).execute()) { 68 String respBody = WXPayBrandUtility.extractBody(httpResponse); 69 if (httpResponse.code() >= 200 && httpResponse.code() < 300) { 70 // 2XX 成功，验证应答签名 71 WXPayBrandUtility.validateResponse(this.wechatPayPublicKeyId, this.wechatPayPublicKey, 72 httpResponse.headers(), respBody); 73 74 // 从HTTP应答报文构建返回数据 75 return WXPayBrandUtility.fromJson(respBody, StockEntity.class); 76 } else { 77 throw new WXPayBrandUtility.ApiException(httpResponse.code(), respBody, httpResponse.headers()); 78 } 79 } catch (IOException e) { 80 throw new UncheckedIOException("Sending request to " + uri + " failed.", e); 81 } 82 } 83 84 private final String brand_id; 85 private final String certificateSerialNo; 86 private final PrivateKey privateKey; 87 private final String wechatPayPublicKeyId; 88 private final PublicKey wechatPayPublicKey; 89 90 public GetStock(String brand_id, String certificateSerialNo, String privateKeyFilePath, String wechatPayPublicKeyId, String wechatPayPublicKeyFilePath) { 91 this.brand_id = brand_id; 92 this.certificateSerialNo = certificateSerialNo; 93 this.privateKey = WXPayBrandUtility.loadPrivateKeyFromPath(privateKeyFilePath); 94 this.wechatPayPublicKeyId = wechatPayPublicKeyId; 95 this.wechatPayPublicKey = WXPayBrandUtility.loadPublicKeyFromPath(wechatPayPublicKeyFilePath); 96 } 97 98 public static class GetStockRequest { 99 @SerializedName("product_coupon_id") 100 @Expose(serialize = false) 101 public String productCouponId; 102 103 @SerializedName("stock_id") 104 @Expose(serialize = false) 105 public String stockId; 106 } 107 108 public static class StockEntity { 109 @SerializedName("product_coupon_id") 110 public String productCouponId; 111 112 @SerializedName("stock_id") 113 public String stockId; 114 115 @SerializedName("remark") 116 public String remark; 117 118 @SerializedName("coupon_code_mode") 119 public CouponCodeMode couponCodeMode; 120 121 @SerializedName("coupon_code_count_info") 122 public CouponCodeCountInfo couponCodeCountInfo; 123 124 @SerializedName("stock_send_rule") 125 public StockSendRule stockSendRule; 126 127 @SerializedName("single_usage_rule") 128 public SingleUsageRule singleUsageRule; 129 130 @SerializedName("progressive_bundle_usage_rule") 131 public StockUsageRule progressiveBundleUsageRule; 132 133 @SerializedName("stock_bundle_info") 134 public StockBundleInfo stockBundleInfo; 135 136 @SerializedName("usage_rule_display_info") 137 public UsageRuleDisplayInfo usageRuleDisplayInfo; 138 139 @SerializedName("coupon_display_info") 140 public CouponDisplayInfo couponDisplayInfo; 141 142 @SerializedName("notify_config") 143 public NotifyConfig notifyConfig; 144 145 @SerializedName("store_scope") 146 public StockStoreScope storeScope; 147 148 @SerializedName("sent_count_info") 149 public StockSentCountInfo sentCountInfo; 150 151 @SerializedName("state") 152 public StockState state; 153 154 @SerializedName("deactivate_request_no") 155 public String deactivateRequestNo; 156 157 @SerializedName("deactivate_time") 158 public String deactivateTime; 159 160 @SerializedName("deactivate_reason") 161 public String deactivateReason; 162 } 163 164 public enum CouponCodeMode { 165 @SerializedName("WECHATPAY") 166 WECHATPAY, 167 @SerializedName("UPLOAD") 168 UPLOAD, 169 @SerializedName("API_ASSIGN") 170 API_ASSIGN 171 } 172 173 public static class CouponCodeCountInfo { 174 @SerializedName("total_count") 175 public Long totalCount; 176 177 @SerializedName("available_count") 178 public Long availableCount; 179 } 180 181 public static class StockSendRule { 182 @SerializedName("max_count") 183 public Long maxCount; 184 185 @SerializedName("max_count_per_day") 186 public Long maxCountPerDay; 187 188 @SerializedName("max_count_per_user") 189 public Long maxCountPerUser; 190 } 191 192 public static class SingleUsageRule { 193 @SerializedName("coupon_available_period") 194 public CouponAvailablePeriod couponAvailablePeriod; 195 196 @SerializedName("normal_coupon") 197 public NormalCouponUsageRule normalCoupon; 198 199 @SerializedName("discount_coupon") 200 public DiscountCouponUsageRule discountCoupon; 201 202 @SerializedName("exchange_coupon") 203 public ExchangeCouponUsageRule exchangeCoupon; 204 } 205 206 public static class StockUsageRule { 207 @SerializedName("coupon_available_period") 208 public CouponAvailablePeriod couponAvailablePeriod; 209 210 @SerializedName("normal_coupon") 211 public NormalCouponUsageRule normalCoupon; 212 213 @SerializedName("discount_coupon") 214 public DiscountCouponUsageRule discountCoupon; 215 216 @SerializedName("exchange_coupon") 217 public ExchangeCouponUsageRule exchangeCoupon; 218 } 219 220 public static class StockBundleInfo { 221 @SerializedName("stock_bundle_id") 222 public String stockBundleId; 223 224 @SerializedName("stock_bundle_index") 225 public Long stockBundleIndex; 226 } 227 228 public static class UsageRuleDisplayInfo { 229 @SerializedName("coupon_usage_method_list") 230 public List<CouponUsageMethod> couponUsageMethodList = new ArrayList<CouponUsageMethod>(); 231 232 @SerializedName("mini_program_appid") 233 public String miniProgramAppid; 234 235 @SerializedName("mini_program_path") 236 public String miniProgramPath; 237 238 @SerializedName("app_path") 239 public String appPath; 240 241 @SerializedName("usage_description") 242 public String usageDescription; 243 244 @SerializedName("coupon_available_store_info") 245 public CouponAvailableStoreInfo couponAvailableStoreInfo; 246 } 247 248 public static class CouponDisplayInfo { 249 @SerializedName("code_display_mode") 250 public CouponCodeDisplayMode codeDisplayMode; 251 252 @SerializedName("background_color") 253 public String backgroundColor; 254 255 @SerializedName("entrance_mini_program") 256 public EntranceMiniProgram entranceMiniProgram; 257 258 @SerializedName("entrance_official_account") 259 public EntranceOfficialAccount entranceOfficialAccount; 260 261 @SerializedName("entrance_finder") 262 public EntranceFinder entranceFinder; 263 } 264 265 public static class NotifyConfig { 266 @SerializedName("notify_appid") 267 public String notifyAppid; 268 } 269 270 public enum StockStoreScope { 271 @SerializedName("NONE") 272 NONE, 273 @SerializedName("ALL") 274 ALL, 275 @SerializedName("SPECIFIC") 276 SPECIFIC 277 } 278 279 public static class StockSentCountInfo { 280 @SerializedName("total_count") 281 public Long totalCount; 282 283 @SerializedName("today_count") 284 public Long todayCount; 285 } 286 287 public enum StockState { 288 @SerializedName("AUDITING") 289 AUDITING, 290 @SerializedName("SENDING") 291 SENDING, 292 @SerializedName("PAUSED") 293 PAUSED, 294 @SerializedName("STOPPED") 295 STOPPED, 296 @SerializedName("DEACTIVATED") 297 DEACTIVATED 298 } 299 300 public static class CouponAvailablePeriod { 301 @SerializedName("available_begin_time") 302 public String availableBeginTime; 303 304 @SerializedName("available_end_time") 305 public String availableEndTime; 306 307 @SerializedName("available_days") 308 public Long availableDays; 309 310 @SerializedName("wait_days_after_receive") 311 public Long waitDaysAfterReceive; 312 313 @SerializedName("weekly_available_period") 314 public FixedWeekPeriod weeklyAvailablePeriod; 315 316 @SerializedName("irregular_available_period_list") 317 public List<TimePeriod> irregularAvailablePeriodList; 318 } 319 320 public static class NormalCouponUsageRule { 321 @SerializedName("threshold") 322 public Long threshold; 323 324 @SerializedName("discount_amount") 325 public Long discountAmount; 326 } 327 328 public static class DiscountCouponUsageRule { 329 @SerializedName("threshold") 330 public Long threshold; 331 332 @SerializedName("percent_off") 333 public Long percentOff; 334 } 335 336 public static class ExchangeCouponUsageRule { 337 @SerializedName("threshold") 338 public Long threshold; 339 340 @SerializedName("exchange_price") 341 public Long exchangePrice; 342 } 343 344 public enum CouponUsageMethod { 345 @SerializedName("OFFLINE") 346 OFFLINE, 347 @SerializedName("MINI_PROGRAM") 348 MINI_PROGRAM, 349 @SerializedName("APP") 350 APP, 351 @SerializedName("PAYMENT_CODE") 352 PAYMENT_CODE 353 } 354 355 public static class CouponAvailableStoreInfo { 356 @SerializedName("description") 357 public String description; 358 359 @SerializedName("mini_program_appid") 360 public String miniProgramAppid; 361 362 @SerializedName("mini_program_path") 363 public String miniProgramPath; 364 } 365 366 public enum CouponCodeDisplayMode { 367 @SerializedName("INVISIBLE") 368 INVISIBLE, 369 @SerializedName("BARCODE") 370 BARCODE, 371 @SerializedName("QRCODE") 372 QRCODE 373 } 374 375 public static class EntranceMiniProgram { 376 @SerializedName("appid") 377 public String appid; 378 379 @SerializedName("path") 380 public String path; 381 382 @SerializedName("entrance_wording") 383 public String entranceWording; 384 385 @SerializedName("guidance_wording") 386 public String guidanceWording; 387 } 388 389 public static class EntranceOfficialAccount { 390 @SerializedName("appid") 391 public String appid; 392 } 393 394 public static class EntranceFinder { 395 @SerializedName("finder_id") 396 public String finderId; 397 398 @SerializedName("finder_video_id") 399 public String finderVideoId; 400 401 @SerializedName("finder_video_cover_image_url") 402 public String finderVideoCoverImageUrl; 403 } 404 405 public static class FixedWeekPeriod { 406 @SerializedName("day_list") 407 public List<WeekEnum> dayList; 408 409 @SerializedName("day_period_list") 410 public List<PeriodOfTheDay> dayPeriodList; 411 } 412 413 public static class TimePeriod { 414 @SerializedName("begin_time") 415 public String beginTime; 416 417 @SerializedName("end_time") 418 public String endTime; 419 } 420 421 public enum WeekEnum { 422 @SerializedName("MONDAY") 423 MONDAY, 424 @SerializedName("TUESDAY") 425 TUESDAY, 426 @SerializedName("WEDNESDAY") 427 WEDNESDAY, 428 @SerializedName("THURSDAY") 429 THURSDAY, 430 @SerializedName("FRIDAY") 431 FRIDAY, 432 @SerializedName("SATURDAY") 433 SATURDAY, 434 @SerializedName("SUNDAY") 435 SUNDAY 436 } 437 438 public static class PeriodOfTheDay { 439 @SerializedName("begin_time") 440 public Long beginTime; 441 442 @SerializedName("end_time") 443 public Long endTime; 444 } 445 446} 447
需配合微信支付工具库 wxpay_utility 使用，请参考Go
1package main 2 3import ( 4 "demo/wxpay_brand_utility" // 引用微信支付工具库，参考 https://pay.weixin.qq.com/doc/brand/4015826866 5 "encoding/json" 6 "fmt" 7 "net/http" 8 "net/url" 9 "strings" 10 "time" 11) 12 13func main() { 14 // TODO: 请准备商户开发必要参数，参考：https://pay.weixin.qq.com/doc/brand/4015415289 15 config, err := wxpay_brand_utility.CreateBrandConfig( 16 "xxxxxxxx", // 品牌ID，是由微信支付系统生成并分配给每个品牌方的唯一标识符，品牌ID获取方式参考 https://pay.weixin.qq.com/doc/brand/4015415289 17 "1DDE55AD98Exxxxxxxxxx", // 品牌API证书序列号，如何获取请参考 https://pay.weixin.qq.com/doc/brand/4015407570 18 "/path/to/apiclient_key.pem", // 品牌API证书私钥文件路径，本地文件路径 19 "PUB_KEY_ID_xxxxxxxxxxxxx", // 微信支付公钥ID，如何获取请参考 https://pay.weixin.qq.com/doc/brand/4015453439 20 "/path/to/wxp_pub.pem", // 微信支付公钥文件路径，本地文件路径 21 ) 22 if err != nil { 23 fmt.Println(err) 24 return 25 } 26 27 request := &GetStockRequest{ 28 ProductCouponId: wxpay_brand_utility.String("1000000013"), 29 StockId: wxpay_brand_utility.String("1000000013001"), 30 } 31 32 response, err := GetStock(config, request) 33 if err != nil { 34 fmt.Printf("请求失败: %+v\n", err) 35 // TODO: 请求失败，根据状态码执行不同的处理 36 return 37 } 38 39 // TODO: 请求成功，继续业务逻辑 40 fmt.Printf("请求成功: %+v\n", response) 41} 42 43func GetStock(config *wxpay_brand_utility.BrandConfig, request *GetStockRequest) (response *StockEntity, err error) { 44 const ( 45 host = "https://api.mch.weixin.qq.com" 46 method = "GET" 47 path = "/brand/marketing/product-coupon/product-coupons/{product_coupon_id}/stocks/{stock_id}" 48 ) 49 50 reqUrl, err := url.Parse(fmt.Sprintf("%s%s", host, path)) 51 if err != nil { 52 return nil, err 53 } 54 reqUrl.Path = strings.Replace(reqUrl.Path, "{product_coupon_id}", url.PathEscape(*request.ProductCouponId), -1) 55 reqUrl.Path = strings.Replace(reqUrl.Path, "{stock_id}", url.PathEscape(*request.StockId), -1) 56 httpRequest, err := http.NewRequest(method, reqUrl.String(), nil) 57 if err != nil { 58 return nil, err 59 } 60 httpRequest.Header.Set("Accept", "application/json") 61 httpRequest.Header.Set("Wechatpay-Serial", config.WechatPayPublicKeyId()) 62 authorization, err := wxpay_brand_utility.BuildAuthorization(config.BrandId(), config.CertificateSerialNo(), config.PrivateKey(), method, reqUrl.RequestURI(), nil) 63 if err != nil { 64 return nil, err 65 } 66 httpRequest.Header.Set("Authorization", authorization) 67 68 client := &http.Client{} 69 httpResponse, err := client.Do(httpRequest) 70 if err != nil { 71 return nil, err 72 } 73 respBody, err := wxpay_brand_utility.ExtractResponseBody(httpResponse) 74 if err != nil { 75 return nil, err 76 } 77 if httpResponse.StatusCode >= 200 && httpResponse.StatusCode < 300 { 78 // 2XX 成功，验证应答签名 79 err = wxpay_brand_utility.ValidateResponse( 80 config.WechatPayPublicKeyId(), 81 config.WechatPayPublicKey(), 82 &httpResponse.Header, 83 respBody, 84 ) 85 if err != nil { 86 return nil, err 87 } 88 response := &StockEntity{} 89 if err := json.Unmarshal(respBody, response); err != nil { 90 return nil, err 91 } 92 93 return response, nil 94 } else { 95 return nil, wxpay_brand_utility.NewApiException( 96 httpResponse.StatusCode, 97 httpResponse.Header, 98 respBody, 99 ) 100 } 101} 102 103type GetStockRequest struct { 104 ProductCouponId *string `json:"product_coupon_id,omitempty"` 105 StockId *string `json:"stock_id,omitempty"` 106} 107 108func (o *GetStockRequest) MarshalJSON() ([]byte, error) { 109 type Alias GetStockRequest 110 a := &struct { 111 ProductCouponId *string `json:"product_coupon_id,omitempty"` 112 StockId *string `json:"stock_id,omitempty"` 113 *Alias 114 }{ 115 // 序列化时移除非 Body 字段 116 ProductCouponId: nil, 117 StockId: nil, 118 Alias: (*Alias)(o), 119 } 120 return json.Marshal(a) 121} 122 123type StockEntity struct { 124 ProductCouponId *string `json:"product_coupon_id,omitempty"` 125 StockId *string `json:"stock_id,omitempty"` 126 Remark *string `json:"remark,omitempty"` 127 CouponCodeMode *CouponCodeMode `json:"coupon_code_mode,omitempty"` 128 CouponCodeCountInfo *CouponCodeCountInfo `json:"coupon_code_count_info,omitempty"` 129 StockSendRule *StockSendRule `json:"stock_send_rule,omitempty"` 130 SingleUsageRule *SingleUsageRule `json:"single_usage_rule,omitempty"` 131 ProgressiveBundleUsageRule *StockUsageRule `json:"progressive_bundle_usage_rule,omitempty"` 132 StockBundleInfo *StockBundleInfo `json:"stock_bundle_info,omitempty"` 133 UsageRuleDisplayInfo *UsageRuleDisplayInfo `json:"usage_rule_display_info,omitempty"` 134 CouponDisplayInfo *CouponDisplayInfo `json:"coupon_display_info,omitempty"` 135 NotifyConfig *NotifyConfig `json:"notify_config,omitempty"` 136 StoreScope *StockStoreScope `json:"store_scope,omitempty"` 137 SentCountInfo *StockSentCountInfo `json:"sent_count_info,omitempty"` 138 State *StockState `json:"state,omitempty"` 139 DeactivateRequestNo *string `json:"deactivate_request_no,omitempty"` 140 DeactivateTime *time.Time `json:"deactivate_time,omitempty"` 141 DeactivateReason *string `json:"deactivate_reason,omitempty"` 142} 143 144type CouponCodeMode string 145 146func (e CouponCodeMode) Ptr() *CouponCodeMode { 147 return &e 148} 149 150const ( 151 COUPONCODEMODE_WECHATPAY CouponCodeMode = "WECHATPAY" 152 COUPONCODEMODE_UPLOAD CouponCodeMode = "UPLOAD" 153 COUPONCODEMODE_API_ASSIGN CouponCodeMode = "API_ASSIGN" 154) 155 156type CouponCodeCountInfo struct { 157 TotalCount *int64 `json:"total_count,omitempty"` 158 AvailableCount *int64 `json:"available_count,omitempty"` 159} 160 161type StockSendRule struct { 162 MaxCount *int64 `json:"max_count,omitempty"` 163 MaxCountPerDay *int64 `json:"max_count_per_day,omitempty"` 164 MaxCountPerUser *int64 `json:"max_count_per_user,omitempty"` 165} 166 167type SingleUsageRule struct { 168 CouponAvailablePeriod *CouponAvailablePeriod `json:"coupon_available_period,omitempty"` 169 NormalCoupon *NormalCouponUsageRule `json:"normal_coupon,omitempty"` 170 DiscountCoupon *DiscountCouponUsageRule `json:"discount_coupon,omitempty"` 171 ExchangeCoupon *ExchangeCouponUsageRule `json:"exchange_coupon,omitempty"` 172} 173 174type StockUsageRule struct { 175 CouponAvailablePeriod *CouponAvailablePeriod `json:"coupon_available_period,omitempty"` 176 NormalCoupon *NormalCouponUsageRule `json:"normal_coupon,omitempty"` 177 DiscountCoupon *DiscountCouponUsageRule `json:"discount_coupon,omitempty"` 178 ExchangeCoupon *ExchangeCouponUsageRule `json:"exchange_coupon,omitempty"` 179} 180 181type StockBundleInfo struct { 182 StockBundleId *string `json:"stock_bundle_id,omitempty"` 183 StockBundleIndex *int64 `json:"stock_bundle_index,omitempty"` 184} 185 186type UsageRuleDisplayInfo struct { 187 CouponUsageMethodList []CouponUsageMethod `json:"coupon_usage_method_list,omitempty"` 188 MiniProgramAppid *string `json:"mini_program_appid,omitempty"` 189 MiniProgramPath *string `json:"mini_program_path,omitempty"` 190 AppPath *string `json:"app_path,omitempty"` 191 UsageDescription *string `json:"usage_description,omitempty"` 192 CouponAvailableStoreInfo *CouponAvailableStoreInfo `json:"coupon_available_store_info,omitempty"` 193} 194 195type CouponDisplayInfo struct { 196 CodeDisplayMode *CouponCodeDisplayMode `json:"code_display_mode,omitempty"` 197 BackgroundColor *string `json:"background_color,omitempty"` 198 EntranceMiniProgram *EntranceMiniProgram `json:"entrance_mini_program,omitempty"` 199 EntranceOfficialAccount *EntranceOfficialAccount `json:"entrance_official_account,omitempty"` 200 EntranceFinder *EntranceFinder `json:"entrance_finder,omitempty"` 201} 202 203type NotifyConfig struct { 204 NotifyAppid *string `json:"notify_appid,omitempty"` 205} 206 207type StockStoreScope string 208 209func (e StockStoreScope) Ptr() *StockStoreScope { 210 return &e 211} 212 213const ( 214 STOCKSTORESCOPE_NONE StockStoreScope = "NONE" 215 STOCKSTORESCOPE_ALL StockStoreScope = "ALL" 216 STOCKSTORESCOPE_SPECIFIC StockStoreScope = "SPECIFIC" 217) 218 219type StockSentCountInfo struct { 220 TotalCount *int64 `json:"total_count,omitempty"` 221 TodayCount *int64 `json:"today_count,omitempty"` 222} 223 224type StockState string 225 226func (e StockState) Ptr() *StockState { 227 return &e 228} 229 230const ( 231 STOCKSTATE_AUDITING StockState = "AUDITING" 232 STOCKSTATE_SENDING StockState = "SENDING" 233 STOCKSTATE_PAUSED StockState = "PAUSED" 234 STOCKSTATE_STOPPED StockState = "STOPPED" 235 STOCKSTATE_DEACTIVATED StockState = "DEACTIVATED" 236) 237 238type CouponAvailablePeriod struct { 239 AvailableBeginTime *string `json:"available_begin_time,omitempty"` 240 AvailableEndTime *string `json:"available_end_time,omitempty"` 241 AvailableDays *int64 `json:"available_days,omitempty"` 242 WaitDaysAfterReceive *int64 `json:"wait_days_after_receive,omitempty"` 243 WeeklyAvailablePeriod *FixedWeekPeriod `json:"weekly_available_period,omitempty"` 244 IrregularAvailablePeriodList []TimePeriod `json:"irregular_available_period_list,omitempty"` 245} 246 247type NormalCouponUsageRule struct { 248 Threshold *int64 `json:"threshold,omitempty"` 249 DiscountAmount *int64 `json:"discount_amount,omitempty"` 250} 251 252type DiscountCouponUsageRule struct { 253 Threshold *int64 `json:"threshold,omitempty"` 254 PercentOff *int64 `json:"percent_off,omitempty"` 255} 256 257type ExchangeCouponUsageRule struct { 258 Threshold *int64 `json:"threshold,omitempty"` 259 ExchangePrice *int64 `json:"exchange_price,omitempty"` 260} 261 262type CouponUsageMethod string 263 264func (e CouponUsageMethod) Ptr() *CouponUsageMethod { 265 return &e 266} 267 268const ( 269 COUPONUSAGEMETHOD_OFFLINE CouponUsageMethod = "OFFLINE" 270 COUPONUSAGEMETHOD_MINI_PROGRAM CouponUsageMethod = "MINI_PROGRAM" 271 COUPONUSAGEMETHOD_APP CouponUsageMethod = "APP" 272 COUPONUSAGEMETHOD_PAYMENT_CODE CouponUsageMethod = "PAYMENT_CODE" 273) 274 275type CouponAvailableStoreInfo struct { 276 Description *string `json:"description,omitempty"` 277 MiniProgramAppid *string `json:"mini_program_appid,omitempty"` 278 MiniProgramPath *string `json:"mini_program_path,omitempty"` 279} 280 281type CouponCodeDisplayMode string 282 283func (e CouponCodeDisplayMode) Ptr() *CouponCodeDisplayMode { 284 return &e 285} 286 287const ( 288 COUPONCODEDISPLAYMODE_INVISIBLE CouponCodeDisplayMode = "INVISIBLE" 289 COUPONCODEDISPLAYMODE_BARCODE CouponCodeDisplayMode = "BARCODE" 290 COUPONCODEDISPLAYMODE_QRCODE CouponCodeDisplayMode = "QRCODE" 291) 292 293type EntranceMiniProgram struct { 294 Appid *string `json:"appid,omitempty"` 295 Path *string `json:"path,omitempty"` 296 EntranceWording *string `json:"entrance_wording,omitempty"` 297 GuidanceWording *string `json:"guidance_wording,omitempty"` 298} 299 300type EntranceOfficialAccount struct { 301 Appid *string `json:"appid,omitempty"` 302} 303 304type EntranceFinder struct { 305 FinderId *string `json:"finder_id,omitempty"` 306 FinderVideoId *string `json:"finder_video_id,omitempty"` 307 FinderVideoCoverImageUrl *string `json:"finder_video_cover_image_url,omitempty"` 308} 309 310type FixedWeekPeriod struct { 311 DayList []WeekEnum `json:"day_list,omitempty"` 312 DayPeriodList []PeriodOfTheDay `json:"day_period_list,omitempty"` 313} 314 315type TimePeriod struct { 316 BeginTime *string `json:"begin_time,omitempty"` 317 EndTime *string `json:"end_time,omitempty"` 318} 319 320type WeekEnum string 321 322func (e WeekEnum) Ptr() *WeekEnum { 323 return &e 324} 325 326const ( 327 WEEKENUM_MONDAY WeekEnum = "MONDAY" 328 WEEKENUM_TUESDAY WeekEnum = "TUESDAY" 329 WEEKENUM_WEDNESDAY WeekEnum = "WEDNESDAY" 330 WEEKENUM_THURSDAY WeekEnum = "THURSDAY" 331 WEEKENUM_FRIDAY WeekEnum = "FRIDAY" 332 WEEKENUM_SATURDAY WeekEnum = "SATURDAY" 333 WEEKENUM_SUNDAY WeekEnum = "SUNDAY" 334) 335 336type PeriodOfTheDay struct { 337 BeginTime *int64 `json:"begin_time,omitempty"` 338 EndTime *int64 `json:"end_time,omitempty"` 339} 340
应答参数
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】自行发券时指定，微信支付系统不再进行自动分配。特别注意：这种模式的商品批次只可由品牌方自行发券，无法在摇一摇有优惠等微信支付渠道投放；商品券的usage_mode为PROGRESSIVE_BUNDLE时不可使用本模式
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 【兑换券使用规则】 当且仅当
|
progressive_bundle_usage_rule 选填 object
【多次优惠使用规则】 当且仅当 usage_mode 为 PROGRESSIVE_BUNDLE 时提供，其他场景不提供
| 属性 | ||||||||||||||||||||||||||||
coupon_available_period 必填 object 【券可核销时间】 确定用户领券后在什么时间段内可以核销
normal_coupon 选填 object 【满减券使用规则】 当且仅当
discount_coupon 选填 object 【折扣券使用规则】 当且仅当
exchange_coupon 选填 object 【兑换券使用规则】 当且仅当
|
stock_bundle_info 选填 object
【批次组信息】 批次所在批次组信息，当且仅当 usage_mode 为 PROGRESSIVE_BUNDLE 时提供
| 属性 |
stock_bundle_id 必填 string(40) 【批次所属批次组ID】 商品券批次组的唯一标识，【创建商品券(多次优惠)】或【添加商品券批次组】时由微信支付生成 stock_bundle_index 必填 integer 【批次在批次组内的次序】 本批次在批次组内的次序，从0开始 |
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，支持小程序、服务号、公众号、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 时提供，返回品牌方调用失效接口时传入的请求流水号
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】时传入的失效原因
应答示例
200 OK
查询单券批次
1{ 2 "product_coupon_id" : "1000000013", 3 "stock_id" : "1000000013001", 4 "remark" : "8月工作日有效批次", 5 "coupon_code_mode" : "UPLOAD", 6 "coupon_code_count_info" : { 7 "total_count" : 0, 8 "available_count" : 0 9 }, 10 "stock_send_rule" : { 11 "max_count" : 10000000, 12 "max_count_per_user" : 1 13 }, 14 "single_usage_rule" : { 15 "coupon_available_period" : { 16 "available_begin_time" : "2025-08-01T00:00:00+08:00", 17 "available_end_time" : "2025-08-31T23:59:59+08:00", 18 "available_days" : 30, 19 "weekly_available_period" : { 20 "day_list" : [ 21 "MONDAY", 22 "TUESDAY", 23 "WEDNESDAY", 24 "THURSDAY", 25 "FRIDAY" 26 ] 27 } 28 } 29 }, 30 "usage_rule_display_info" : { 31 "coupon_usage_method_list" : [ 32 "OFFLINE", 33 "MINI_PROGRAM", 34 "PAYMENT_CODE" 35 ], 36 "mini_program_appid" : "wx1234567890", 37 "mini_program_path" : "/pages/index/product", 38 "usage_description" : "工作日可用", 39 "coupon_available_store_info" : { 40 "description" : "所有门店可用，可使用小程序查看门店列表", 41 "mini_program_appid" : "wx1234567890", 42 "mini_program_path" : "/pages/index/store-list" 43 } 44 }, 45 "coupon_display_info" : { 46 "code_display_mode" : "QRCODE", 47 "background_color" : "Color010", 48 "entrance_mini_program" : { 49 "appid" : "wx1234567890", 50 "path" : "/pages/index/product", 51 "entrance_wording" : "欢迎选购", 52 "guidance_wording" : "获取更多优惠" 53 }, 54 "entrance_official_account" : { 55 "appid" : "wx1234567890" 56 }, 57 "entrance_finder" : { 58 "finder_id" : "gh_12345678", 59 "finder_video_id" : "UDFsdf24df34dD456Hdf34", 60 "finder_video_cover_image_url" : "https://wxpaylogo.qpic.cn/wxpaylogo/xxxxx/xxx" 61 } 62 }, 63 "notify_config" : { 64 "notify_appid" : "wx4fd12345678" 65 }, 66 "store_scope" : "NONE", 67 "sent_count_info" : { 68 "total_count" : 0, 69 "today_count" : 0 70 }, 71 "state" : "SENDING" 72} 73
查询多次优惠批次
1{ 2 "product_coupon_id" : "1000000014", 3 "stock_id" : "1000000014002", 4 "remark" : "8月工作日有效批次", 5 "coupon_code_mode" : "UPLOAD", 6 "coupon_code_count_info" : { 7 "total_count" : 0, 8 "available_count" : 0 9 }, 10 "stock_send_rule" : { 11 "max_count" : 10000000, 12 "max_count_per_user" : 1 13 }, 14 "progressive_bundle_usage_rule" : { 15 "coupon_available_period" : { 16 "available_begin_time" : "2025-08-01T00:00:00+08:00", 17 "available_end_time" : "2025-08-31T23:59:59+08:00", 18 "available_days" : 30, 19 "weekly_available_period" : { 20 "day_list" : [ 21 "MONDAY", 22 "TUESDAY", 23 "WEDNESDAY", 24 "THURSDAY", 25 "FRIDAY" 26 ] 27 } 28 }, 29 "discount_coupon" : { 30 "threshold" : 10000, 31 "percent_off" : 20 32 } 33 }, 34 "stock_bundle_info" : { 35 "stock_bundle_id" : "712315129419284901", 36 "stock_bundle_index" : 1 37 }, 38 "usage_rule_display_info" : { 39 "coupon_usage_method_list" : [ 40 "OFFLINE", 41 "MINI_PROGRAM", 42 "PAYMENT_CODE" 43 ], 44 "mini_program_appid" : "wx1234567890", 45 "mini_program_path" : "/pages/index/product", 46 "usage_description" : "工作日可用", 47 "coupon_available_store_info" : { 48 "description" : "所有门店可用，可使用小程序查看门店列表", 49 "mini_program_appid" : "wx1234567890", 50 "mini_program_path" : "/pages/index/store-list" 51 } 52 }, 53 "coupon_display_info" : { 54 "code_display_mode" : "QRCODE", 55 "background_color" : "Color010", 56 "entrance_mini_program" : { 57 "appid" : "wx1234567890", 58 "path" : "/pages/index/product", 59 "entrance_wording" : "欢迎选购", 60 "guidance_wording" : "获取更多优惠" 61 }, 62 "entrance_official_account" : { 63 "appid" : "wx1234567890" 64 }, 65 "entrance_finder" : { 66 "finder_id" : "gh_12345678", 67 "finder_video_id" : "UDFsdf24df34dD456Hdf34", 68 "finder_video_cover_image_url" : "https://wxpaylogo.qpic.cn/wxpaylogo/xxxxx/xxx" 69 } 70 }, 71 "notify_config" : { 72 "notify_appid" : "wx4fd12345678" 73 }, 74 "store_scope" : "NONE", 75 "sent_count_info" : { 76 "total_count" : 0, 77 "today_count" : 0 78 }, 79 "state" : "SENDING" 80} 81
错误码
以下是本接口返回的错误码列表。详细错误码规则，请参考微信支付接口规则-错误码和错误提示
状态码 | 错误码 | 描述 | 解决方案 |
|---|---|---|---|
400 | PARAM_ERROR | 参数错误 | 请根据错误提示正确传入参数 |
400 | INVALID_REQUEST | HTTP 请求不符合微信支付 APIv3 接口规则 | 请参阅 接口规则 |
401 | SIGN_ERROR | 验证不通过 | 请参阅 签名常见问题 |
500 | SYSTEM_ERROR | 系统异常，请稍后重试 | 请稍后重试 |
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 |
