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