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