指定券状态查询用户商品券列表
更新时间:2025.09.02品牌方可以通过本接口查询已经发放给用户的特定状态的商品券
前置条件:已经给用户发券成功
频率限制:500/s
接口说明
支持商户:【普通服务商】
请求方式:【GET】/v3/marketing/partner/product-coupon/users/{openid}/coupons
请求域名:【主域名】https://api.mch.weixin.qq.com 使用该域名将访问就近的接入点
【备域名】https://api2.mch.weixin.qq.com 使用该域名将访问异地的接入点 ,指引点击查看
请求参数
Header HTTP头参数
Authorization 必填 string
请参考签名认证生成认证信息
Accept 必填 string
请设置为application/json
path 路径参数
openid 必填 string
【用户OpenID】 OpenID信息,用户在AppID下的唯一标识,获取方式参考OpenID
query 查询参数
product_coupon_id 选填 string
【商品券ID】 商品券的唯一标识,创建商品券时由微信支付生成。查询指定商品券下的用户商品券列表,不传入时查询范围扩大至品牌下的所有商品券
stock_id 选填 string
【批次ID】 商品券批次的唯一标识,商品券批次创建时由微信支付生成(可使用创建商品券或添加商品券批次创建)。查询指定商品券批次下的用户商品券列表。
appid 必填 string
【公众账号AppID】 请传入与当前调用接口服务商有绑定关系的AppID,支持小程序、服务号、公众号、APP类型的AppID
coupon_state 选填 string
【用户商品券状态】 查询指定状态的用户商品券
可选取值
CONFIRMING: 待确认,用户商品券发放需要品牌方调用确认发放用户商品券接口后才能生效PENDING: 已发放待生效,用户商品券已发放成功但尚未到达可用开始时间EFFECTIVE: 已生效,用户商品券已成功发放且到达可用开始时间USED: 已核销,用户商品券已核销EXPIRED: 已过期,用户商品券已超过有效期,不再可用DELETED: 已删除,用户主动删除该券DEACTIVATED: 已失效,品牌方主动调用失效用户商品券接口使用户商品券失效
page_size 选填 integer
【分页大小】 单次拉取的数据条数上限,不填默认为20,最大值50
page_token 选填 string
【分页Token】 分页查询时,需要传入上一次调用返回的 next_page_token,首次调用不填
brand_id 必填 string
【品牌ID】 微信支付为品牌方分配的唯一标识,该品牌应与服务商存在授权关系
请求示例
GET
1curl -X GET \ 2 https://api.mch.weixin.qq.com/v3/marketing/partner/product-coupon/users/oh-394z-6CGkNoJrsDLTTUKiAnp4/coupons?product_coupon_id=1002323&stock_id=100232301&appid=wx233544546545989&coupon_state=USED&page_size=20&page_token=MTIzMjUK&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 ListUserProductCoupons { 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/users/{openid}/coupons"; 29 30 public static void main(String[] args) { 31 // TODO: 请准备商户开发必要参数,参考:https://pay.weixin.qq.com/doc/v3/partner/4013080340 32 ListUserProductCoupons client = new ListUserProductCoupons( 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 ListUserProductCouponsRequest request = new ListUserProductCouponsRequest(); 41 request.openid = "oh-394z-6CGkNoJrsDLTTUKiAnp4"; 42 request.productCouponId = "1002323"; 43 request.stockId = "100232301"; 44 request.appid = "wx233544546545989"; 45 request.couponState = UserProductCouponState.USED; 46 request.pageSize = 20L; 47 request.pageToken = "MTIzMjUK"; 48 request.brandId = "120344"; 49 try { 50 ListUserProductCouponsResponse response = client.run(request); 51 // TODO: 请求成功,继续业务逻辑 52 System.out.println(response); 53 } catch (WXPayUtility.ApiException e) { 54 // TODO: 请求失败,根据状态码执行不同的逻辑 55 e.printStackTrace(); 56 } 57 } 58 59 public ListUserProductCouponsResponse run(ListUserProductCouponsRequest request) { 60 String uri = PATH; 61 uri = uri.replace("{openid}", WXPayUtility.urlEncode(request.openid)); 62 Map<String, Object> args = new HashMap<>(); 63 args.put("product_coupon_id", request.productCouponId); 64 args.put("stock_id", request.stockId); 65 args.put("appid", request.appid); 66 args.put("coupon_state", request.couponState); 67 args.put("page_size", request.pageSize); 68 args.put("page_token", request.pageToken); 69 args.put("brand_id", request.brandId); 70 String queryString = WXPayUtility.urlEncode(args); 71 if (!queryString.isEmpty()) { 72 uri = uri + "?" + queryString; 73 } 74 75 Request.Builder reqBuilder = new Request.Builder().url(HOST + uri); 76 reqBuilder.addHeader("Accept", "application/json"); 77 reqBuilder.addHeader("Wechatpay-Serial", wechatPayPublicKeyId); 78 reqBuilder.addHeader("Authorization", WXPayUtility.buildAuthorization(mchid, certificateSerialNo, privateKey, METHOD, uri, null)); 79 reqBuilder.method(METHOD, null); 80 Request httpRequest = reqBuilder.build(); 81 82 // 发送HTTP请求 83 OkHttpClient client = new OkHttpClient.Builder().build(); 84 try (Response httpResponse = client.newCall(httpRequest).execute()) { 85 String respBody = WXPayUtility.extractBody(httpResponse); 86 if (httpResponse.code() >= 200 && httpResponse.code() < 300) { 87 // 2XX 成功,验证应答签名 88 WXPayUtility.validateResponse(this.wechatPayPublicKeyId, this.wechatPayPublicKey, 89 httpResponse.headers(), respBody); 90 91 // 从HTTP应答报文构建返回数据 92 return WXPayUtility.fromJson(respBody, ListUserProductCouponsResponse.class); 93 } else { 94 throw new WXPayUtility.ApiException(httpResponse.code(), respBody, httpResponse.headers()); 95 } 96 } catch (IOException e) { 97 throw new UncheckedIOException("Sending request to " + uri + " failed.", e); 98 } 99 } 100 101 private final String mchid; 102 private final String certificateSerialNo; 103 private final PrivateKey privateKey; 104 private final String wechatPayPublicKeyId; 105 private final PublicKey wechatPayPublicKey; 106 107 public ListUserProductCoupons(String mchid, String certificateSerialNo, String privateKeyFilePath, String wechatPayPublicKeyId, String wechatPayPublicKeyFilePath) { 108 this.mchid = mchid; 109 this.certificateSerialNo = certificateSerialNo; 110 this.privateKey = WXPayUtility.loadPrivateKeyFromPath(privateKeyFilePath); 111 this.wechatPayPublicKeyId = wechatPayPublicKeyId; 112 this.wechatPayPublicKey = WXPayUtility.loadPublicKeyFromPath(wechatPayPublicKeyFilePath); 113 } 114 115 public static class ListUserProductCouponsRequest { 116 @SerializedName("product_coupon_id") 117 @Expose(serialize = false) 118 public String productCouponId; 119 120 @SerializedName("stock_id") 121 @Expose(serialize = false) 122 public String stockId; 123 124 @SerializedName("appid") 125 @Expose(serialize = false) 126 public String appid; 127 128 @SerializedName("openid") 129 @Expose(serialize = false) 130 public String openid; 131 132 @SerializedName("page_size") 133 @Expose(serialize = false) 134 public Long pageSize; 135 136 @SerializedName("page_token") 137 @Expose(serialize = false) 138 public String pageToken; 139 140 @SerializedName("brand_id") 141 @Expose(serialize = false) 142 public String brandId; 143 144 @SerializedName("coupon_state") 145 @Expose(serialize = false) 146 public UserProductCouponState couponState; 147 } 148 149 public static class ListUserProductCouponsResponse { 150 @SerializedName("total_count") 151 public Long totalCount; 152 153 @SerializedName("user_coupon_list") 154 public List<UserProductCouponEntity> userCouponList; 155 156 @SerializedName("next_page_token") 157 public String nextPageToken; 158 } 159 160 public enum UserProductCouponState { 161 @SerializedName("CONFIRMING") 162 CONFIRMING, 163 @SerializedName("PENDING") 164 PENDING, 165 @SerializedName("EFFECTIVE") 166 EFFECTIVE, 167 @SerializedName("USED") 168 USED, 169 @SerializedName("EXPIRED") 170 EXPIRED, 171 @SerializedName("DELETED") 172 DELETED, 173 @SerializedName("DEACTIVATED") 174 DEACTIVATED 175 } 176 177 public static class UserProductCouponEntity { 178 @SerializedName("coupon_code") 179 public String couponCode; 180 181 @SerializedName("coupon_state") 182 public UserProductCouponState couponState; 183 184 @SerializedName("valid_begin_time") 185 public String validBeginTime; 186 187 @SerializedName("valid_end_time") 188 public String validEndTime; 189 190 @SerializedName("receive_time") 191 public String receiveTime; 192 193 @SerializedName("send_request_no") 194 public String sendRequestNo; 195 196 @SerializedName("send_channel") 197 public UserProductCouponSendChannel sendChannel; 198 199 @SerializedName("confirm_request_no") 200 public String confirmRequestNo; 201 202 @SerializedName("confirm_time") 203 public String confirmTime; 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("single_usage_detail") 215 public SingleUsageDetail singleUsageDetail; 216 217 @SerializedName("sequential_usage_detail") 218 public SequentialUsageDetail sequentialUsageDetail; 219 220 @SerializedName("product_coupon") 221 public ProductCouponEntity productCoupon; 222 223 @SerializedName("stock") 224 public StockEntity stock; 225 226 @SerializedName("attach") 227 public String attach; 228 229 @SerializedName("channel_custom_info") 230 public String channelCustomInfo; 231 232 @SerializedName("brand_id") 233 public String brandId; 234 235 @SerializedName("coupon_tag_info") 236 public CouponTagInfo couponTagInfo; 237 } 238 239 public enum UserProductCouponSendChannel { 240 @SerializedName("BRAND_MANAGE") 241 BRAND_MANAGE, 242 @SerializedName("API") 243 API, 244 @SerializedName("RECEIVE_COMPONENT") 245 RECEIVE_COMPONENT 246 } 247 248 public static class SingleUsageDetail { 249 @SerializedName("use_request_no") 250 public String useRequestNo; 251 252 @SerializedName("use_time") 253 public String useTime; 254 255 @SerializedName("associated_order_info") 256 public UserProductCouponAssociatedOrderInfo associatedOrderInfo; 257 258 @SerializedName("return_request_no") 259 public String returnRequestNo; 260 261 @SerializedName("return_time") 262 public String returnTime; 263 } 264 265 public static class SequentialUsageDetail { 266 @SerializedName("total_count") 267 public Long totalCount; 268 269 @SerializedName("used_count") 270 public Long usedCount; 271 272 @SerializedName("detail_item_list") 273 public List<SequentialUsageDetailItem> detailItemList; 274 } 275 276 public static class ProductCouponEntity { 277 @SerializedName("product_coupon_id") 278 public String productCouponId; 279 280 @SerializedName("scope") 281 public ProductCouponScope scope; 282 283 @SerializedName("type") 284 public ProductCouponType type; 285 286 @SerializedName("usage_mode") 287 public UsageMode usageMode; 288 289 @SerializedName("single_usage_info") 290 public SingleUsageInfo singleUsageInfo; 291 292 @SerializedName("sequential_usage_info") 293 public SequentialUsageInfo sequentialUsageInfo; 294 295 @SerializedName("display_info") 296 public ProductCouponDisplayInfo displayInfo; 297 298 @SerializedName("out_product_no") 299 public String outProductNo; 300 301 @SerializedName("state") 302 public ProductCouponState state; 303 304 @SerializedName("deactivate_request_no") 305 public String deactivateRequestNo; 306 307 @SerializedName("deactivate_time") 308 public String deactivateTime; 309 310 @SerializedName("deactivate_reason") 311 public String deactivateReason; 312 313 @SerializedName("brand_id") 314 public String brandId; 315 } 316 317 public static class StockEntity { 318 @SerializedName("product_coupon_id") 319 public String productCouponId; 320 321 @SerializedName("stock_id") 322 public String stockId; 323 324 @SerializedName("remark") 325 public String remark; 326 327 @SerializedName("coupon_code_mode") 328 public CouponCodeMode couponCodeMode; 329 330 @SerializedName("coupon_code_count_info") 331 public CouponCodeCountInfo couponCodeCountInfo; 332 333 @SerializedName("stock_send_rule") 334 public StockSendRule stockSendRule; 335 336 @SerializedName("single_usage_rule") 337 public SingleUsageRule singleUsageRule; 338 339 @SerializedName("sequential_usage_rule") 340 public SequentialUsageRule sequentialUsageRule; 341 342 @SerializedName("usage_rule_display_info") 343 public UsageRuleDisplayInfo usageRuleDisplayInfo; 344 345 @SerializedName("coupon_display_info") 346 public CouponDisplayInfo couponDisplayInfo; 347 348 @SerializedName("notify_config") 349 public NotifyConfig notifyConfig; 350 351 @SerializedName("store_scope") 352 public StockStoreScope storeScope; 353 354 @SerializedName("sent_count_info") 355 public StockSentCountInfo sentCountInfo; 356 357 @SerializedName("state") 358 public StockState state; 359 360 @SerializedName("deactivate_request_no") 361 public String deactivateRequestNo; 362 363 @SerializedName("deactivate_time") 364 public String deactivateTime; 365 366 @SerializedName("deactivate_reason") 367 public String deactivateReason; 368 369 @SerializedName("brand_id") 370 public String brandId; 371 } 372 373 public static class CouponTagInfo { 374 @SerializedName("coupon_tag_list") 375 public List<UserProductCouponTag> couponTagList; 376 377 @SerializedName("member_tag_info") 378 public MemberTagInfo memberTagInfo; 379 } 380 381 public static class UserProductCouponAssociatedOrderInfo { 382 @SerializedName("transaction_id") 383 public String transactionId; 384 385 @SerializedName("out_trade_no") 386 public String outTradeNo; 387 388 @SerializedName("mchid") 389 public String mchid; 390 391 @SerializedName("sub_mchid") 392 public String subMchid; 393 } 394 395 public static class SequentialUsageDetailItem { 396 @SerializedName("detail_state") 397 public UserProductCouponUsageDetailItemState detailState; 398 399 @SerializedName("valid_begin_time") 400 public String validBeginTime; 401 402 @SerializedName("valid_end_time") 403 public String validEndTime; 404 405 @SerializedName("use_request_no") 406 public String useRequestNo; 407 408 @SerializedName("use_time") 409 public String useTime; 410 411 @SerializedName("associated_order_info") 412 public UserProductCouponAssociatedOrderInfo associatedOrderInfo; 413 414 @SerializedName("return_request_no") 415 public String returnRequestNo; 416 417 @SerializedName("return_time") 418 public String returnTime; 419 420 @SerializedName("delete_time") 421 public String deleteTime; 422 } 423 424 public enum ProductCouponScope { 425 @SerializedName("ALL") 426 ALL, 427 @SerializedName("SINGLE") 428 SINGLE 429 } 430 431 public enum ProductCouponType { 432 @SerializedName("NORMAL") 433 NORMAL, 434 @SerializedName("DISCOUNT") 435 DISCOUNT, 436 @SerializedName("EXCHANGE") 437 EXCHANGE 438 } 439 440 public enum UsageMode { 441 @SerializedName("SINGLE") 442 SINGLE, 443 @SerializedName("SEQUENTIAL") 444 SEQUENTIAL 445 } 446 447 public static class SingleUsageInfo { 448 @SerializedName("normal_coupon") 449 public NormalCouponUsageRule normalCoupon; 450 451 @SerializedName("discount_coupon") 452 public DiscountCouponUsageRule discountCoupon; 453 } 454 455 public static class SequentialUsageInfo { 456 @SerializedName("type") 457 public SequentialUsageType type; 458 459 @SerializedName("count") 460 public Long count; 461 462 @SerializedName("available_days") 463 public Long availableDays; 464 465 @SerializedName("interval_days") 466 public Long intervalDays; 467 } 468 469 public static class ProductCouponDisplayInfo { 470 @SerializedName("name") 471 public String name; 472 473 @SerializedName("image_url") 474 public String imageUrl; 475 476 @SerializedName("background_url") 477 public String backgroundUrl; 478 479 @SerializedName("detail_image_url_list") 480 public List<String> detailImageUrlList; 481 482 @SerializedName("original_price") 483 public Long originalPrice; 484 485 @SerializedName("combo_package_list") 486 public List<ComboPackage> comboPackageList; 487 } 488 489 public enum ProductCouponState { 490 @SerializedName("AUDITING") 491 AUDITING, 492 @SerializedName("EFFECTIVE") 493 EFFECTIVE, 494 @SerializedName("DEACTIVATED") 495 DEACTIVATED 496 } 497 498 public enum CouponCodeMode { 499 @SerializedName("WECHATPAY") 500 WECHATPAY, 501 @SerializedName("UPLOAD") 502 UPLOAD, 503 @SerializedName("API_ASSIGN") 504 API_ASSIGN 505 } 506 507 public static class CouponCodeCountInfo { 508 @SerializedName("total_count") 509 public Long totalCount; 510 511 @SerializedName("available_count") 512 public Long availableCount; 513 } 514 515 public static class StockSendRule { 516 @SerializedName("max_count") 517 public Long maxCount; 518 519 @SerializedName("max_count_per_day") 520 public Long maxCountPerDay; 521 522 @SerializedName("max_count_per_user") 523 public Long maxCountPerUser; 524 } 525 526 public static class SingleUsageRule { 527 @SerializedName("coupon_available_period") 528 public SingleCouponAvailablePeriod couponAvailablePeriod; 529 530 @SerializedName("normal_coupon") 531 public NormalCouponUsageRule normalCoupon; 532 533 @SerializedName("discount_coupon") 534 public DiscountCouponUsageRule discountCoupon; 535 536 @SerializedName("exchange_coupon") 537 public ExchangeCouponUsageRule exchangeCoupon; 538 } 539 540 public static class SequentialUsageRule { 541 @SerializedName("coupon_available_period") 542 public SequentialCouponAvailablePeriod couponAvailablePeriod; 543 544 @SerializedName("normal_coupon_list") 545 public List<NormalCouponUsageRule> normalCouponList; 546 547 @SerializedName("discount_coupon_list") 548 public List<DiscountCouponUsageRule> discountCouponList; 549 550 @SerializedName("exchange_coupon_list") 551 public List<ExchangeCouponUsageRule> exchangeCouponList; 552 553 @SerializedName("special_first") 554 public Boolean specialFirst; 555 } 556 557 public static class UsageRuleDisplayInfo { 558 @SerializedName("coupon_usage_method_list") 559 public List<CouponUsageMethod> couponUsageMethodList = new ArrayList<CouponUsageMethod>(); 560 561 @SerializedName("mini_program_appid") 562 public String miniProgramAppid; 563 564 @SerializedName("mini_program_path") 565 public String miniProgramPath; 566 567 @SerializedName("app_path") 568 public String appPath; 569 570 @SerializedName("usage_description") 571 public String usageDescription; 572 573 @SerializedName("coupon_available_store_info") 574 public CouponAvailableStoreInfo couponAvailableStoreInfo; 575 } 576 577 public static class CouponDisplayInfo { 578 @SerializedName("code_display_mode") 579 public CouponCodeDisplayMode codeDisplayMode; 580 581 @SerializedName("background_color") 582 public String backgroundColor; 583 584 @SerializedName("entrance_mini_program") 585 public EntranceMiniProgram entranceMiniProgram; 586 587 @SerializedName("entrance_official_account") 588 public EntranceOfficialAccount entranceOfficialAccount; 589 590 @SerializedName("entrance_finder") 591 public EntranceFinder entranceFinder; 592 } 593 594 public static class NotifyConfig { 595 @SerializedName("notify_appid") 596 public String notifyAppid; 597 } 598 599 public enum StockStoreScope { 600 @SerializedName("NONE") 601 NONE, 602 @SerializedName("ALL") 603 ALL, 604 @SerializedName("SPECIFIC") 605 SPECIFIC 606 } 607 608 public static class StockSentCountInfo { 609 @SerializedName("total_count") 610 public Long totalCount; 611 612 @SerializedName("today_count") 613 public Long todayCount; 614 } 615 616 public enum StockState { 617 @SerializedName("AUDITING") 618 AUDITING, 619 @SerializedName("SENDING") 620 SENDING, 621 @SerializedName("PAUSED") 622 PAUSED, 623 @SerializedName("STOPPED") 624 STOPPED, 625 @SerializedName("DEACTIVATED") 626 DEACTIVATED 627 } 628 629 public enum UserProductCouponTag { 630 @SerializedName("MEMBER") 631 MEMBER 632 } 633 634 public static class MemberTagInfo { 635 @SerializedName("member_card_id") 636 public String memberCardId; 637 } 638 639 public enum UserProductCouponUsageDetailItemState { 640 @SerializedName("PENDING") 641 PENDING, 642 @SerializedName("EFFECTIVE") 643 EFFECTIVE, 644 @SerializedName("USED") 645 USED, 646 @SerializedName("EXPIRED") 647 EXPIRED, 648 @SerializedName("DELETED") 649 DELETED, 650 @SerializedName("DEACTIVATED") 651 DEACTIVATED 652 } 653 654 public static class NormalCouponUsageRule { 655 @SerializedName("threshold") 656 public Long threshold; 657 658 @SerializedName("discount_amount") 659 public Long discountAmount; 660 } 661 662 public static class DiscountCouponUsageRule { 663 @SerializedName("threshold") 664 public Long threshold; 665 666 @SerializedName("percent_off") 667 public Long percentOff; 668 } 669 670 public enum SequentialUsageType { 671 @SerializedName("INCREMENTAL") 672 INCREMENTAL, 673 @SerializedName("EQUAL") 674 EQUAL 675 } 676 677 public static class ComboPackage { 678 @SerializedName("name") 679 public String name; 680 681 @SerializedName("pick_count") 682 public Long pickCount; 683 684 @SerializedName("choice_list") 685 public List<ComboPackageChoice> choiceList = new ArrayList<ComboPackageChoice>(); 686 } 687 688 public static class SingleCouponAvailablePeriod { 689 @SerializedName("available_begin_time") 690 public String availableBeginTime; 691 692 @SerializedName("available_end_time") 693 public String availableEndTime; 694 695 @SerializedName("available_days") 696 public Long availableDays; 697 698 @SerializedName("wait_days_after_receive") 699 public Long waitDaysAfterReceive; 700 701 @SerializedName("weekly_available_period") 702 public FixedWeekPeriod weeklyAvailablePeriod; 703 704 @SerializedName("irregular_available_period_list") 705 public List<TimePeriod> irregularAvailablePeriodList; 706 } 707 708 public static class ExchangeCouponUsageRule { 709 @SerializedName("threshold") 710 public Long threshold; 711 712 @SerializedName("exchange_price") 713 public Long exchangePrice; 714 } 715 716 public static class SequentialCouponAvailablePeriod { 717 @SerializedName("available_begin_time") 718 public String availableBeginTime; 719 720 @SerializedName("available_end_time") 721 public String availableEndTime; 722 723 @SerializedName("wait_days_after_receive") 724 public Long waitDaysAfterReceive; 725 726 @SerializedName("weekly_available_period") 727 public FixedWeekPeriod weeklyAvailablePeriod; 728 729 @SerializedName("irregular_available_period_list") 730 public List<TimePeriod> irregularAvailablePeriodList; 731 } 732 733 public enum CouponUsageMethod { 734 @SerializedName("OFFLINE") 735 OFFLINE, 736 @SerializedName("MINI_PROGRAM") 737 MINI_PROGRAM, 738 @SerializedName("APP") 739 APP, 740 @SerializedName("PAYMENT_CODE") 741 PAYMENT_CODE 742 } 743 744 public static class CouponAvailableStoreInfo { 745 @SerializedName("description") 746 public String description; 747 748 @SerializedName("mini_program_appid") 749 public String miniProgramAppid; 750 751 @SerializedName("mini_program_path") 752 public String miniProgramPath; 753 } 754 755 public enum CouponCodeDisplayMode { 756 @SerializedName("INVISIBLE") 757 INVISIBLE, 758 @SerializedName("BARCODE") 759 BARCODE, 760 @SerializedName("QRCODE") 761 QRCODE 762 } 763 764 public static class EntranceMiniProgram { 765 @SerializedName("appid") 766 public String appid; 767 768 @SerializedName("path") 769 public String path; 770 771 @SerializedName("entrance_wording") 772 public String entranceWording; 773 774 @SerializedName("guidance_wording") 775 public String guidanceWording; 776 } 777 778 public static class EntranceOfficialAccount { 779 @SerializedName("appid") 780 public String appid; 781 } 782 783 public static class EntranceFinder { 784 @SerializedName("finder_id") 785 public String finderId; 786 787 @SerializedName("finder_video_id") 788 public String finderVideoId; 789 790 @SerializedName("finder_video_cover_image_url") 791 public String finderVideoCoverImageUrl; 792 } 793 794 public static class ComboPackageChoice { 795 @SerializedName("name") 796 public String name; 797 798 @SerializedName("price") 799 public Long price; 800 801 @SerializedName("count") 802 public Long count; 803 804 @SerializedName("image_url") 805 public String imageUrl; 806 807 @SerializedName("mini_program_appid") 808 public String miniProgramAppid; 809 810 @SerializedName("mini_program_path") 811 public String miniProgramPath; 812 } 813 814 public static class FixedWeekPeriod { 815 @SerializedName("day_list") 816 public List<WeekEnum> dayList; 817 818 @SerializedName("day_period_list") 819 public List<PeriodOfTheDay> dayPeriodList; 820 } 821 822 public static class TimePeriod { 823 @SerializedName("begin_time") 824 public String beginTime; 825 826 @SerializedName("end_time") 827 public String endTime; 828 } 829 830 public enum WeekEnum { 831 @SerializedName("MONDAY") 832 MONDAY, 833 @SerializedName("TUESDAY") 834 TUESDAY, 835 @SerializedName("WEDNESDAY") 836 WEDNESDAY, 837 @SerializedName("THURSDAY") 838 THURSDAY, 839 @SerializedName("FRIDAY") 840 FRIDAY, 841 @SerializedName("SATURDAY") 842 SATURDAY, 843 @SerializedName("SUNDAY") 844 SUNDAY 845 } 846 847 public static class PeriodOfTheDay { 848 @SerializedName("begin_time") 849 public Long beginTime; 850 851 @SerializedName("end_time") 852 public Long endTime; 853 } 854 855} 856
需配合微信支付工具库 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 := &ListUserProductCouponsRequest{ 28 ProductCouponId: wxpay_utility.String("1002323"), 29 StockId: wxpay_utility.String("100232301"), 30 Appid: wxpay_utility.String("wx233544546545989"), 31 Openid: wxpay_utility.String("oh-394z-6CGkNoJrsDLTTUKiAnp4"), 32 CouponState: USERPRODUCTCOUPONSTATE_USED.Ptr(), 33 PageSize: wxpay_utility.Int64(20), 34 PageToken: wxpay_utility.String("MTIzMjUK"), 35 BrandId: wxpay_utility.String("120344"), 36 } 37 38 response, err := ListUserProductCoupons(config, request) 39 if err != nil { 40 fmt.Printf("请求失败: %+v\n", err) 41 // TODO: 请求失败,根据状态码执行不同的处理 42 return 43 } 44 45 // TODO: 请求成功,继续业务逻辑 46 fmt.Printf("请求成功: %+v\n", response) 47} 48 49func ListUserProductCoupons(config *wxpay_utility.MchConfig, request *ListUserProductCouponsRequest) (response *ListUserProductCouponsResponse, err error) { 50 const ( 51 host = "https://api.mch.weixin.qq.com" 52 method = "GET" 53 path = "/v3/marketing/partner/product-coupon/users/{openid}/coupons" 54 ) 55 56 reqUrl, err := url.Parse(fmt.Sprintf("%s%s", host, path)) 57 if err != nil { 58 return nil, err 59 } 60 reqUrl.Path = strings.Replace(reqUrl.Path, "{openid}", url.PathEscape(*request.Openid), -1) 61 query := reqUrl.Query() 62 if request.ProductCouponId != nil { 63 query.Add("product_coupon_id", *request.ProductCouponId) 64 } 65 if request.StockId != nil { 66 query.Add("stock_id", *request.StockId) 67 } 68 if request.Appid != nil { 69 query.Add("appid", *request.Appid) 70 } 71 if request.CouponState != nil { 72 query.Add("coupon_state", fmt.Sprintf("%v", *request.CouponState)) 73 } 74 if request.PageSize != nil { 75 query.Add("page_size", fmt.Sprintf("%v", *request.PageSize)) 76 } 77 if request.PageToken != nil { 78 query.Add("page_token", *request.PageToken) 79 } 80 if request.BrandId != nil { 81 query.Add("brand_id", *request.BrandId) 82 } 83 reqUrl.RawQuery = query.Encode() 84 httpRequest, err := http.NewRequest(method, reqUrl.String(), nil) 85 if err != nil { 86 return nil, err 87 } 88 httpRequest.Header.Set("Accept", "application/json") 89 httpRequest.Header.Set("Wechatpay-Serial", config.WechatPayPublicKeyId()) 90 authorization, err := wxpay_utility.BuildAuthorization(config.MchId(), config.CertificateSerialNo(), config.PrivateKey(), method, reqUrl.RequestURI(), nil) 91 if err != nil { 92 return nil, err 93 } 94 httpRequest.Header.Set("Authorization", authorization) 95 96 client := &http.Client{} 97 httpResponse, err := client.Do(httpRequest) 98 if err != nil { 99 return nil, err 100 } 101 respBody, err := wxpay_utility.ExtractResponseBody(httpResponse) 102 if err != nil { 103 return nil, err 104 } 105 if httpResponse.StatusCode >= 200 && httpResponse.StatusCode < 300 { 106 // 2XX 成功,验证应答签名 107 err = wxpay_utility.ValidateResponse( 108 config.WechatPayPublicKeyId(), 109 config.WechatPayPublicKey(), 110 &httpResponse.Header, 111 respBody, 112 ) 113 if err != nil { 114 return nil, err 115 } 116 response := &ListUserProductCouponsResponse{} 117 if err := json.Unmarshal(respBody, response); err != nil { 118 return nil, err 119 } 120 121 return response, nil 122 } else { 123 return nil, wxpay_utility.NewApiException( 124 httpResponse.StatusCode, 125 httpResponse.Header, 126 respBody, 127 ) 128 } 129} 130 131type ListUserProductCouponsRequest struct { 132 ProductCouponId *string `json:"product_coupon_id,omitempty"` 133 StockId *string `json:"stock_id,omitempty"` 134 Appid *string `json:"appid,omitempty"` 135 Openid *string `json:"openid,omitempty"` 136 PageSize *int64 `json:"page_size,omitempty"` 137 PageToken *string `json:"page_token,omitempty"` 138 BrandId *string `json:"brand_id,omitempty"` 139 CouponState *UserProductCouponState `json:"coupon_state,omitempty"` 140} 141 142func (o *ListUserProductCouponsRequest) MarshalJSON() ([]byte, error) { 143 type Alias ListUserProductCouponsRequest 144 a := &struct { 145 ProductCouponId *string `json:"product_coupon_id,omitempty"` 146 StockId *string `json:"stock_id,omitempty"` 147 Appid *string `json:"appid,omitempty"` 148 Openid *string `json:"openid,omitempty"` 149 PageSize *int64 `json:"page_size,omitempty"` 150 PageToken *string `json:"page_token,omitempty"` 151 BrandId *string `json:"brand_id,omitempty"` 152 CouponState *UserProductCouponState `json:"coupon_state,omitempty"` 153 *Alias 154 }{ 155 // 序列化时移除非 Body 字段 156 ProductCouponId: nil, 157 StockId: nil, 158 Appid: nil, 159 Openid: nil, 160 PageSize: nil, 161 PageToken: nil, 162 BrandId: nil, 163 CouponState: nil, 164 Alias: (*Alias)(o), 165 } 166 return json.Marshal(a) 167} 168 169type ListUserProductCouponsResponse struct { 170 TotalCount *int64 `json:"total_count,omitempty"` 171 UserCouponList []UserProductCouponEntity `json:"user_coupon_list,omitempty"` 172 NextPageToken *string `json:"next_page_token,omitempty"` 173} 174 175type UserProductCouponState string 176 177func (e UserProductCouponState) Ptr() *UserProductCouponState { 178 return &e 179} 180 181const ( 182 USERPRODUCTCOUPONSTATE_CONFIRMING UserProductCouponState = "CONFIRMING" 183 USERPRODUCTCOUPONSTATE_PENDING UserProductCouponState = "PENDING" 184 USERPRODUCTCOUPONSTATE_EFFECTIVE UserProductCouponState = "EFFECTIVE" 185 USERPRODUCTCOUPONSTATE_USED UserProductCouponState = "USED" 186 USERPRODUCTCOUPONSTATE_EXPIRED UserProductCouponState = "EXPIRED" 187 USERPRODUCTCOUPONSTATE_DELETED UserProductCouponState = "DELETED" 188 USERPRODUCTCOUPONSTATE_DEACTIVATED UserProductCouponState = "DEACTIVATED" 189) 190 191type UserProductCouponEntity struct { 192 CouponCode *string `json:"coupon_code,omitempty"` 193 CouponState *UserProductCouponState `json:"coupon_state,omitempty"` 194 ValidBeginTime *time.Time `json:"valid_begin_time,omitempty"` 195 ValidEndTime *time.Time `json:"valid_end_time,omitempty"` 196 ReceiveTime *string `json:"receive_time,omitempty"` 197 SendRequestNo *string `json:"send_request_no,omitempty"` 198 SendChannel *UserProductCouponSendChannel `json:"send_channel,omitempty"` 199 ConfirmRequestNo *string `json:"confirm_request_no,omitempty"` 200 ConfirmTime *time.Time `json:"confirm_time,omitempty"` 201 DeactivateRequestNo *string `json:"deactivate_request_no,omitempty"` 202 DeactivateTime *string `json:"deactivate_time,omitempty"` 203 DeactivateReason *string `json:"deactivate_reason,omitempty"` 204 SingleUsageDetail *SingleUsageDetail `json:"single_usage_detail,omitempty"` 205 SequentialUsageDetail *SequentialUsageDetail `json:"sequential_usage_detail,omitempty"` 206 ProductCoupon *ProductCouponEntity `json:"product_coupon,omitempty"` 207 Stock *StockEntity `json:"stock,omitempty"` 208 Attach *string `json:"attach,omitempty"` 209 ChannelCustomInfo *string `json:"channel_custom_info,omitempty"` 210 BrandId *string `json:"brand_id,omitempty"` 211 CouponTagInfo *CouponTagInfo `json:"coupon_tag_info,omitempty"` 212} 213 214type UserProductCouponSendChannel string 215 216func (e UserProductCouponSendChannel) Ptr() *UserProductCouponSendChannel { 217 return &e 218} 219 220const ( 221 USERPRODUCTCOUPONSENDCHANNEL_BRAND_MANAGE UserProductCouponSendChannel = "BRAND_MANAGE" 222 USERPRODUCTCOUPONSENDCHANNEL_API UserProductCouponSendChannel = "API" 223 USERPRODUCTCOUPONSENDCHANNEL_RECEIVE_COMPONENT UserProductCouponSendChannel = "RECEIVE_COMPONENT" 224) 225 226type SingleUsageDetail struct { 227 UseRequestNo *string `json:"use_request_no,omitempty"` 228 UseTime *time.Time `json:"use_time,omitempty"` 229 AssociatedOrderInfo *UserProductCouponAssociatedOrderInfo `json:"associated_order_info,omitempty"` 230 ReturnRequestNo *string `json:"return_request_no,omitempty"` 231 ReturnTime *time.Time `json:"return_time,omitempty"` 232} 233 234type SequentialUsageDetail struct { 235 TotalCount *int64 `json:"total_count,omitempty"` 236 UsedCount *int64 `json:"used_count,omitempty"` 237 DetailItemList []SequentialUsageDetailItem `json:"detail_item_list,omitempty"` 238} 239 240type ProductCouponEntity struct { 241 ProductCouponId *string `json:"product_coupon_id,omitempty"` 242 Scope *ProductCouponScope `json:"scope,omitempty"` 243 Type *ProductCouponType `json:"type,omitempty"` 244 UsageMode *UsageMode `json:"usage_mode,omitempty"` 245 SingleUsageInfo *SingleUsageInfo `json:"single_usage_info,omitempty"` 246 SequentialUsageInfo *SequentialUsageInfo `json:"sequential_usage_info,omitempty"` 247 DisplayInfo *ProductCouponDisplayInfo `json:"display_info,omitempty"` 248 OutProductNo *string `json:"out_product_no,omitempty"` 249 State *ProductCouponState `json:"state,omitempty"` 250 DeactivateRequestNo *string `json:"deactivate_request_no,omitempty"` 251 DeactivateTime *string `json:"deactivate_time,omitempty"` 252 DeactivateReason *string `json:"deactivate_reason,omitempty"` 253 BrandId *string `json:"brand_id,omitempty"` 254} 255 256type StockEntity struct { 257 ProductCouponId *string `json:"product_coupon_id,omitempty"` 258 StockId *string `json:"stock_id,omitempty"` 259 Remark *string `json:"remark,omitempty"` 260 CouponCodeMode *CouponCodeMode `json:"coupon_code_mode,omitempty"` 261 CouponCodeCountInfo *CouponCodeCountInfo `json:"coupon_code_count_info,omitempty"` 262 StockSendRule *StockSendRule `json:"stock_send_rule,omitempty"` 263 SingleUsageRule *SingleUsageRule `json:"single_usage_rule,omitempty"` 264 SequentialUsageRule *SequentialUsageRule `json:"sequential_usage_rule,omitempty"` 265 UsageRuleDisplayInfo *UsageRuleDisplayInfo `json:"usage_rule_display_info,omitempty"` 266 CouponDisplayInfo *CouponDisplayInfo `json:"coupon_display_info,omitempty"` 267 NotifyConfig *NotifyConfig `json:"notify_config,omitempty"` 268 StoreScope *StockStoreScope `json:"store_scope,omitempty"` 269 SentCountInfo *StockSentCountInfo `json:"sent_count_info,omitempty"` 270 State *StockState `json:"state,omitempty"` 271 DeactivateRequestNo *string `json:"deactivate_request_no,omitempty"` 272 DeactivateTime *time.Time `json:"deactivate_time,omitempty"` 273 DeactivateReason *string `json:"deactivate_reason,omitempty"` 274 BrandId *string `json:"brand_id,omitempty"` 275} 276 277type CouponTagInfo struct { 278 CouponTagList []UserProductCouponTag `json:"coupon_tag_list,omitempty"` 279 MemberTagInfo *MemberTagInfo `json:"member_tag_info,omitempty"` 280} 281 282type UserProductCouponAssociatedOrderInfo struct { 283 TransactionId *string `json:"transaction_id,omitempty"` 284 OutTradeNo *string `json:"out_trade_no,omitempty"` 285 Mchid *string `json:"mchid,omitempty"` 286 SubMchid *string `json:"sub_mchid,omitempty"` 287} 288 289type SequentialUsageDetailItem struct { 290 DetailState *UserProductCouponUsageDetailItemState `json:"detail_state,omitempty"` 291 ValidBeginTime *time.Time `json:"valid_begin_time,omitempty"` 292 ValidEndTime *time.Time `json:"valid_end_time,omitempty"` 293 UseRequestNo *string `json:"use_request_no,omitempty"` 294 UseTime *time.Time `json:"use_time,omitempty"` 295 AssociatedOrderInfo *UserProductCouponAssociatedOrderInfo `json:"associated_order_info,omitempty"` 296 ReturnRequestNo *string `json:"return_request_no,omitempty"` 297 ReturnTime *time.Time `json:"return_time,omitempty"` 298 DeleteTime *time.Time `json:"delete_time,omitempty"` 299} 300 301type ProductCouponScope string 302 303func (e ProductCouponScope) Ptr() *ProductCouponScope { 304 return &e 305} 306 307const ( 308 PRODUCTCOUPONSCOPE_ALL ProductCouponScope = "ALL" 309 PRODUCTCOUPONSCOPE_SINGLE ProductCouponScope = "SINGLE" 310) 311 312type ProductCouponType string 313 314func (e ProductCouponType) Ptr() *ProductCouponType { 315 return &e 316} 317 318const ( 319 PRODUCTCOUPONTYPE_NORMAL ProductCouponType = "NORMAL" 320 PRODUCTCOUPONTYPE_DISCOUNT ProductCouponType = "DISCOUNT" 321 PRODUCTCOUPONTYPE_EXCHANGE ProductCouponType = "EXCHANGE" 322) 323 324type UsageMode string 325 326func (e UsageMode) Ptr() *UsageMode { 327 return &e 328} 329 330const ( 331 USAGEMODE_SINGLE UsageMode = "SINGLE" 332 USAGEMODE_SEQUENTIAL UsageMode = "SEQUENTIAL" 333) 334 335type SingleUsageInfo struct { 336 NormalCoupon *NormalCouponUsageRule `json:"normal_coupon,omitempty"` 337 DiscountCoupon *DiscountCouponUsageRule `json:"discount_coupon,omitempty"` 338} 339 340type SequentialUsageInfo struct { 341 Type *SequentialUsageType `json:"type,omitempty"` 342 Count *int64 `json:"count,omitempty"` 343 AvailableDays *int64 `json:"available_days,omitempty"` 344 IntervalDays *int64 `json:"interval_days,omitempty"` 345} 346 347type ProductCouponDisplayInfo struct { 348 Name *string `json:"name,omitempty"` 349 ImageUrl *string `json:"image_url,omitempty"` 350 BackgroundUrl *string `json:"background_url,omitempty"` 351 DetailImageUrlList []string `json:"detail_image_url_list,omitempty"` 352 OriginalPrice *int64 `json:"original_price,omitempty"` 353 ComboPackageList []ComboPackage `json:"combo_package_list,omitempty"` 354} 355 356type ProductCouponState string 357 358func (e ProductCouponState) Ptr() *ProductCouponState { 359 return &e 360} 361 362const ( 363 PRODUCTCOUPONSTATE_AUDITING ProductCouponState = "AUDITING" 364 PRODUCTCOUPONSTATE_EFFECTIVE ProductCouponState = "EFFECTIVE" 365 PRODUCTCOUPONSTATE_DEACTIVATED ProductCouponState = "DEACTIVATED" 366) 367 368type CouponCodeMode string 369 370func (e CouponCodeMode) Ptr() *CouponCodeMode { 371 return &e 372} 373 374const ( 375 COUPONCODEMODE_WECHATPAY CouponCodeMode = "WECHATPAY" 376 COUPONCODEMODE_UPLOAD CouponCodeMode = "UPLOAD" 377 COUPONCODEMODE_API_ASSIGN CouponCodeMode = "API_ASSIGN" 378) 379 380type CouponCodeCountInfo struct { 381 TotalCount *int64 `json:"total_count,omitempty"` 382 AvailableCount *int64 `json:"available_count,omitempty"` 383} 384 385type StockSendRule struct { 386 MaxCount *int64 `json:"max_count,omitempty"` 387 MaxCountPerDay *int64 `json:"max_count_per_day,omitempty"` 388 MaxCountPerUser *int64 `json:"max_count_per_user,omitempty"` 389} 390 391type SingleUsageRule struct { 392 CouponAvailablePeriod *SingleCouponAvailablePeriod `json:"coupon_available_period,omitempty"` 393 NormalCoupon *NormalCouponUsageRule `json:"normal_coupon,omitempty"` 394 DiscountCoupon *DiscountCouponUsageRule `json:"discount_coupon,omitempty"` 395 ExchangeCoupon *ExchangeCouponUsageRule `json:"exchange_coupon,omitempty"` 396} 397 398type SequentialUsageRule struct { 399 CouponAvailablePeriod *SequentialCouponAvailablePeriod `json:"coupon_available_period,omitempty"` 400 NormalCouponList []NormalCouponUsageRule `json:"normal_coupon_list,omitempty"` 401 DiscountCouponList []DiscountCouponUsageRule `json:"discount_coupon_list,omitempty"` 402 ExchangeCouponList []ExchangeCouponUsageRule `json:"exchange_coupon_list,omitempty"` 403 SpecialFirst *bool `json:"special_first,omitempty"` 404} 405 406type UsageRuleDisplayInfo struct { 407 CouponUsageMethodList []CouponUsageMethod `json:"coupon_usage_method_list,omitempty"` 408 MiniProgramAppid *string `json:"mini_program_appid,omitempty"` 409 MiniProgramPath *string `json:"mini_program_path,omitempty"` 410 AppPath *string `json:"app_path,omitempty"` 411 UsageDescription *string `json:"usage_description,omitempty"` 412 CouponAvailableStoreInfo *CouponAvailableStoreInfo `json:"coupon_available_store_info,omitempty"` 413} 414 415type CouponDisplayInfo struct { 416 CodeDisplayMode *CouponCodeDisplayMode `json:"code_display_mode,omitempty"` 417 BackgroundColor *string `json:"background_color,omitempty"` 418 EntranceMiniProgram *EntranceMiniProgram `json:"entrance_mini_program,omitempty"` 419 EntranceOfficialAccount *EntranceOfficialAccount `json:"entrance_official_account,omitempty"` 420 EntranceFinder *EntranceFinder `json:"entrance_finder,omitempty"` 421} 422 423type NotifyConfig struct { 424 NotifyAppid *string `json:"notify_appid,omitempty"` 425} 426 427type StockStoreScope string 428 429func (e StockStoreScope) Ptr() *StockStoreScope { 430 return &e 431} 432 433const ( 434 STOCKSTORESCOPE_NONE StockStoreScope = "NONE" 435 STOCKSTORESCOPE_ALL StockStoreScope = "ALL" 436 STOCKSTORESCOPE_SPECIFIC StockStoreScope = "SPECIFIC" 437) 438 439type StockSentCountInfo struct { 440 TotalCount *int64 `json:"total_count,omitempty"` 441 TodayCount *int64 `json:"today_count,omitempty"` 442} 443 444type StockState string 445 446func (e StockState) Ptr() *StockState { 447 return &e 448} 449 450const ( 451 STOCKSTATE_AUDITING StockState = "AUDITING" 452 STOCKSTATE_SENDING StockState = "SENDING" 453 STOCKSTATE_PAUSED StockState = "PAUSED" 454 STOCKSTATE_STOPPED StockState = "STOPPED" 455 STOCKSTATE_DEACTIVATED StockState = "DEACTIVATED" 456) 457 458type UserProductCouponTag string 459 460func (e UserProductCouponTag) Ptr() *UserProductCouponTag { 461 return &e 462} 463 464const ( 465 USERPRODUCTCOUPONTAG_MEMBER UserProductCouponTag = "MEMBER" 466) 467 468type MemberTagInfo struct { 469 MemberCardId *string `json:"member_card_id,omitempty"` 470} 471 472type UserProductCouponUsageDetailItemState string 473 474func (e UserProductCouponUsageDetailItemState) Ptr() *UserProductCouponUsageDetailItemState { 475 return &e 476} 477 478const ( 479 USERPRODUCTCOUPONUSAGEDETAILITEMSTATE_PENDING UserProductCouponUsageDetailItemState = "PENDING" 480 USERPRODUCTCOUPONUSAGEDETAILITEMSTATE_EFFECTIVE UserProductCouponUsageDetailItemState = "EFFECTIVE" 481 USERPRODUCTCOUPONUSAGEDETAILITEMSTATE_USED UserProductCouponUsageDetailItemState = "USED" 482 USERPRODUCTCOUPONUSAGEDETAILITEMSTATE_EXPIRED UserProductCouponUsageDetailItemState = "EXPIRED" 483 USERPRODUCTCOUPONUSAGEDETAILITEMSTATE_DELETED UserProductCouponUsageDetailItemState = "DELETED" 484 USERPRODUCTCOUPONUSAGEDETAILITEMSTATE_DEACTIVATED UserProductCouponUsageDetailItemState = "DEACTIVATED" 485) 486 487type NormalCouponUsageRule struct { 488 Threshold *int64 `json:"threshold,omitempty"` 489 DiscountAmount *int64 `json:"discount_amount,omitempty"` 490} 491 492type DiscountCouponUsageRule struct { 493 Threshold *int64 `json:"threshold,omitempty"` 494 PercentOff *int64 `json:"percent_off,omitempty"` 495} 496 497type SequentialUsageType string 498 499func (e SequentialUsageType) Ptr() *SequentialUsageType { 500 return &e 501} 502 503const ( 504 SEQUENTIALUSAGETYPE_INCREMENTAL SequentialUsageType = "INCREMENTAL" 505 SEQUENTIALUSAGETYPE_EQUAL SequentialUsageType = "EQUAL" 506) 507 508type ComboPackage struct { 509 Name *string `json:"name,omitempty"` 510 PickCount *int64 `json:"pick_count,omitempty"` 511 ChoiceList []ComboPackageChoice `json:"choice_list,omitempty"` 512} 513 514type SingleCouponAvailablePeriod struct { 515 AvailableBeginTime *string `json:"available_begin_time,omitempty"` 516 AvailableEndTime *string `json:"available_end_time,omitempty"` 517 AvailableDays *int64 `json:"available_days,omitempty"` 518 WaitDaysAfterReceive *int64 `json:"wait_days_after_receive,omitempty"` 519 WeeklyAvailablePeriod *FixedWeekPeriod `json:"weekly_available_period,omitempty"` 520 IrregularAvailablePeriodList []TimePeriod `json:"irregular_available_period_list,omitempty"` 521} 522 523type ExchangeCouponUsageRule struct { 524 Threshold *int64 `json:"threshold,omitempty"` 525 ExchangePrice *int64 `json:"exchange_price,omitempty"` 526} 527 528type SequentialCouponAvailablePeriod struct { 529 AvailableBeginTime *string `json:"available_begin_time,omitempty"` 530 AvailableEndTime *string `json:"available_end_time,omitempty"` 531 WaitDaysAfterReceive *int64 `json:"wait_days_after_receive,omitempty"` 532 WeeklyAvailablePeriod *FixedWeekPeriod `json:"weekly_available_period,omitempty"` 533 IrregularAvailablePeriodList []TimePeriod `json:"irregular_available_period_list,omitempty"` 534} 535 536type CouponUsageMethod string 537 538func (e CouponUsageMethod) Ptr() *CouponUsageMethod { 539 return &e 540} 541 542const ( 543 COUPONUSAGEMETHOD_OFFLINE CouponUsageMethod = "OFFLINE" 544 COUPONUSAGEMETHOD_MINI_PROGRAM CouponUsageMethod = "MINI_PROGRAM" 545 COUPONUSAGEMETHOD_APP CouponUsageMethod = "APP" 546 COUPONUSAGEMETHOD_PAYMENT_CODE CouponUsageMethod = "PAYMENT_CODE" 547) 548 549type CouponAvailableStoreInfo struct { 550 Description *string `json:"description,omitempty"` 551 MiniProgramAppid *string `json:"mini_program_appid,omitempty"` 552 MiniProgramPath *string `json:"mini_program_path,omitempty"` 553} 554 555type CouponCodeDisplayMode string 556 557func (e CouponCodeDisplayMode) Ptr() *CouponCodeDisplayMode { 558 return &e 559} 560 561const ( 562 COUPONCODEDISPLAYMODE_INVISIBLE CouponCodeDisplayMode = "INVISIBLE" 563 COUPONCODEDISPLAYMODE_BARCODE CouponCodeDisplayMode = "BARCODE" 564 COUPONCODEDISPLAYMODE_QRCODE CouponCodeDisplayMode = "QRCODE" 565) 566 567type EntranceMiniProgram struct { 568 Appid *string `json:"appid,omitempty"` 569 Path *string `json:"path,omitempty"` 570 EntranceWording *string `json:"entrance_wording,omitempty"` 571 GuidanceWording *string `json:"guidance_wording,omitempty"` 572} 573 574type EntranceOfficialAccount struct { 575 Appid *string `json:"appid,omitempty"` 576} 577 578type EntranceFinder struct { 579 FinderId *string `json:"finder_id,omitempty"` 580 FinderVideoId *string `json:"finder_video_id,omitempty"` 581 FinderVideoCoverImageUrl *string `json:"finder_video_cover_image_url,omitempty"` 582} 583 584type ComboPackageChoice struct { 585 Name *string `json:"name,omitempty"` 586 Price *int64 `json:"price,omitempty"` 587 Count *int64 `json:"count,omitempty"` 588 ImageUrl *string `json:"image_url,omitempty"` 589 MiniProgramAppid *string `json:"mini_program_appid,omitempty"` 590 MiniProgramPath *string `json:"mini_program_path,omitempty"` 591} 592 593type FixedWeekPeriod struct { 594 DayList []WeekEnum `json:"day_list,omitempty"` 595 DayPeriodList []PeriodOfTheDay `json:"day_period_list,omitempty"` 596} 597 598type TimePeriod struct { 599 BeginTime *string `json:"begin_time,omitempty"` 600 EndTime *string `json:"end_time,omitempty"` 601} 602 603type WeekEnum string 604 605func (e WeekEnum) Ptr() *WeekEnum { 606 return &e 607} 608 609const ( 610 WEEKENUM_MONDAY WeekEnum = "MONDAY" 611 WEEKENUM_TUESDAY WeekEnum = "TUESDAY" 612 WEEKENUM_WEDNESDAY WeekEnum = "WEDNESDAY" 613 WEEKENUM_THURSDAY WeekEnum = "THURSDAY" 614 WEEKENUM_FRIDAY WeekEnum = "FRIDAY" 615 WEEKENUM_SATURDAY WeekEnum = "SATURDAY" 616 WEEKENUM_SUNDAY WeekEnum = "SUNDAY" 617) 618 619type PeriodOfTheDay struct { 620 BeginTime *int64 `json:"begin_time,omitempty"` 621 EndTime *int64 `json:"end_time,omitempty"` 622} 623
应答参数
200 OK
total_count 必填 integer
【总个数】 满足条件的数据总条数,当且仅当 page_token 为空时提供。
user_coupon_list 选填 array[object]
【用户商品券列表】 指定状态的用户商品券列表信息
| 属性 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
coupon_code 必填 string(40) 【用户商品券Code】 用户商品券的唯一标识 coupon_state 必填 string 【用户商品券状态】 可选取值
valid_begin_time 必填 string 【有效期开始时间】 用户商品券可用开始时间,遵循rfc3339标准格式,格式为yyyy-MM-DDTHH:mm:ss+TIMEZONE,yyyy-MM-DD表示年月日,T出现在字符串中,表示time元素的开头,HH:mm:ss表示时分秒,TIMEZONE表示时区(+08:00表示东八区时间,领先UTC 8小时,即北京时间) valid_end_time 必填 string 【有效期结束时间】 用户商品券可用结束时间。遵循rfc3339标准格式,格式为yyyy-MM-DDTHH:mm:ss+TIMEZONE,yyyy-MM-DD表示年月日,T出现在字符串中,表示time元素的开头,HH:mm:ss表示时分秒,TIMEZONE表示时区(+08:00表示东八区时间,领先UTC 8小时,即北京时间) receive_time 必填 string 【领券时间】 用户领券时间。遵循rfc3339标准格式,格式为yyyy-MM-DDTHH:mm:ss+TIMEZONE,yyyy-MM-DD表示年月日,T出现在字符串中,表示time元素的开头,HH:mm:ss表示时分秒,TIMEZONE表示时区(+08:00表示东八区时间,领先UTC 8小时,即北京时间) send_request_no 必填 string(128) 【发券请求单号】 发券时传入的请求流水号 send_channel 必填 string 【发券渠道】 描述用户商品券是经由什么渠道发送的 可选取值
confirm_request_no 选填 string 【确认请求单号】 品牌方确认发券请求时传入的的请求流水号。当且仅当 品牌方调用确认发放用户商品券接口后提供。 confirm_time 选填 string 【确认发放时间】 品牌方确认发券时间,当且仅当 品牌方调用确认发放用户商品券接口后提供。遵循rfc3339标准格式,格式为yyyy-MM-DDTHH:mm:ss+TIMEZONE,yyyy-MM-DD表示年月日,T出现在字符串中,表示time元素的开头,HH:mm:ss表示时分秒,TIMEZONE表示时区(+08:00表示东八区时间,领先UTC 8小时,即北京时间) deactivate_request_no 选填 string 【失效请求单号】 品牌方失效券请求时传入的的请求流水号。当且仅当 deactivate_time 选填 string 【失效时间】 失效时间,当且仅当 deactivate_reason 选填 string 【失效原因】 失效券的原因,当且仅当 single_usage_detail 选填 object 【单券使用详情】 当且仅当
sequential_usage_detail 选填 object 【多次优惠使用详情】 当且仅当
product_coupon 必填 object 【商品券信息】 该用户商品券对应的商品券详情
stock 必填 object 【批次信息】 该用户商品券发券时使用的批次详情
attach 选填 string 【自定义附加信息】 调用发券接口时品牌方使用 注: 发券渠道多样,只有品牌方通过发券接口发放以及通过预发券接口预发放并使用领券组件发放的券才会在查询和回调中携带此字段,其他渠道发放的券 channel_custom_info 选填 string(1000) 【渠道自定义信息】 使用微信支付提供的其他渠道(比如「摇一摇有优惠」)发放商品券时,渠道可能会设置该渠道特定的自定义信息,请根据 brand_id 必填 string 【品牌ID】 微信支付为品牌方分配的唯一标识,该品牌应与服务商存在授权关系 coupon_tag_info 选填 object 【用户商品券标签信息】 用户商品券标签信息
|
next_page_token 选填 string(100)
【下一页Token】 分页查询时,如果还有更多数据,会返回下一页的Token,请在下一次查询时设置在 page_token 中;如果已无更多数据,则不返回此字段。
应答示例
200 OK
1{ 2 "total_count" : 20, 3 "user_coupon_list" : [ 4 { 5 "coupon_code" : "123446565767", 6 "coupon_state" : "USED", 7 "valid_begin_time" : "2025-01-01T00:00+08:00", 8 "valid_end_time" : "2025-01-30T23:59:59+08:00", 9 "receive_time" : "2025-01-01T09:10:00+08:00", 10 "send_request_no" : "MCHSEND202003101234", 11 "send_channel" : "BRAND_MANAGE", 12 "confirm_request_no" : "MCHCONFIRM202003101234", 13 "confirm_time" : "2025-01-20T13:29:35+08:00", 14 "deactivate_request_no" : "1002600620019090123143254436", 15 "deactivate_time" : "2025-01-20T13:29:35+08:00", 16 "deactivate_reason" : "商品已下线", 17 "single_usage_detail" : { 18 "use_request_no" : "MCHUSE202003101234", 19 "use_time" : "2025-07-20T13:29:35+08:00", 20 "associated_order_info" : { 21 "transaction_id" : "4200000000123456789123456789", 22 "out_trade_no" : "trade_no_20250724123456", 23 "mchid" : "1234567890", 24 "sub_mchid" : "1234567890" 25 }, 26 "return_request_no" : "MCHRETURN202003101234", 27 "return_time" : "2025-07-20T14:29:35+08:00" 28 }, 29 "sequential_usage_detail" : { 30 "total_count" : 10, 31 "used_count" : 3, 32 "detail_item_list" : [ 33 { 34 "detail_state" : "USED", 35 "valid_begin_time" : "2025-07-24T00:00+08:00", 36 "valid_end_time" : "2025-07-30T23:59:59+08:00", 37 "use_request_no" : "MCHUSE202003101234", 38 "use_time" : "2025-07-20T13:29:35+08:00", 39 "associated_order_info" : { 40 "transaction_id" : "4200000000123456789123456789", 41 "out_trade_no" : "trade_no_20250724123456", 42 "mchid" : "1234567890", 43 "sub_mchid" : "1234567890" 44 }, 45 "return_request_no" : "MCHRETURN202003101234", 46 "return_time" : "2025-07-20T14:29:35+08:00", 47 "delete_time" : "2025-07-20T14:29:35+08:00" 48 } 49 ] 50 }, 51 "product_coupon" : { 52 "product_coupon_id" : "1002323", 53 "scope" : "ALL", 54 "type" : "NORMAL", 55 "usage_mode" : "SEQUENTIAL", 56 "single_usage_info" : { 57 "normal_coupon" : { 58 "threshold" : 10000, 59 "discount_amount" : 100 60 }, 61 "discount_coupon" : { 62 "threshold" : 10000, 63 "percent_off" : 30 64 } 65 }, 66 "sequential_usage_info" : { 67 "type" : "EQUAL", 68 "count" : 10, 69 "available_days" : 10, 70 "interval_days" : 1 71 }, 72 "display_info" : { 73 "name" : "全场满100可减10元", 74 "image_url" : "https://wxpaylogo.qpic.cn/wxpaylogo/xxxxx/xxx", 75 "background_url" : "https://wxpaylogo.qpic.cn/wxpaylogo/xxxxx/xxx", 76 "detail_image_url_list" : [ 77 "https://wxpaylogo.qpic.cn/wxpaylogo/xxxxx/xxx" 78 ], 79 "original_price" : 10000, 80 "combo_package_list" : [ 81 { 82 "name" : "咖啡2选1", 83 "pick_count" : 3, 84 "choice_list" : [ 85 { 86 "name" : "美式", 87 "price" : 10000, 88 "count" : 2, 89 "image_url" : "https://wxpaylogo.qpic.cn/wxpaylogo/xxxxx/xxx", 90 "mini_program_appid" : "wx4fd12345678", 91 "mini_program_path" : "/pages/index/index" 92 } 93 ] 94 } 95 ] 96 }, 97 "out_product_no" : "Product_1234567890", 98 "state" : "AUDITING", 99 "deactivate_request_no" : "1002600620019090123143254436", 100 "deactivate_time" : "2025-06-20T13:29:35+08:00", 101 "deactivate_reason" : "商品已下架", 102 "brand_id" : "120344" 103 }, 104 "stock" : { 105 "product_coupon_id" : "200000001", 106 "stock_id" : "123456789", 107 "remark" : "满减券", 108 "coupon_code_mode" : "UPLOAD", 109 "coupon_code_count_info" : { 110 "total_count" : 10000, 111 "available_count" : 999 112 }, 113 "stock_send_rule" : { 114 "max_count" : 10000000, 115 "max_count_per_day" : 10000, 116 "max_count_per_user" : 1 117 }, 118 "single_usage_rule" : { 119 "coupon_available_period" : { 120 "available_begin_time" : "2025-01-01T00:00:00+08:00", 121 "available_end_time" : "2025-10-01T00:00:00+08:00", 122 "available_days" : 10, 123 "wait_days_after_receive" : 1, 124 "weekly_available_period" : { 125 "day_list" : [ 126 "MONDAY" 127 ], 128 "day_period_list" : [ 129 { 130 "begin_time" : 60, 131 "end_time" : 86399 132 } 133 ] 134 }, 135 "irregular_available_period_list" : [ 136 { 137 "begin_time" : "2025-01-01T00:00:00+08:00", 138 "end_time" : "2025-10-01T00:00:00+08:00" 139 } 140 ] 141 }, 142 "normal_coupon" : { 143 "threshold" : 10000, 144 "discount_amount" : 100 145 }, 146 "discount_coupon" : { 147 "threshold" : 10000, 148 "percent_off" : 30 149 }, 150 "exchange_coupon" : { 151 "threshold" : 10000, 152 "exchange_price" : 100 153 } 154 }, 155 "sequential_usage_rule" : { 156 "coupon_available_period" : { 157 "available_begin_time" : "2025-01-01T00:00:00+08:00", 158 "available_end_time" : "2025-10-01T00:00:00+08:00", 159 "wait_days_after_receive" : 1, 160 "weekly_available_period" : { 161 "day_list" : [ 162 "MONDAY" 163 ], 164 "day_period_list" : [ 165 { 166 "begin_time" : 60, 167 "end_time" : 86399 168 } 169 ] 170 }, 171 "irregular_available_period_list" : [ 172 { 173 "begin_time" : "2025-01-01T00:00:00+08:00", 174 "end_time" : "2025-10-01T00:00:00+08:00" 175 } 176 ] 177 }, 178 "normal_coupon_list" : [ 179 { 180 "threshold" : 10000, 181 "discount_amount" : 100 182 } 183 ], 184 "discount_coupon_list" : [ 185 { 186 "threshold" : 10000, 187 "percent_off" : 30 188 } 189 ], 190 "exchange_coupon_list" : [ 191 { 192 "threshold" : 10000, 193 "exchange_price" : 100 194 } 195 ], 196 "special_first" : false 197 }, 198 "usage_rule_display_info" : { 199 "coupon_usage_method_list" : [ 200 "MINI_PROGRAM" 201 ], 202 "mini_program_appid" : "wx1234567890", 203 "mini_program_path" : "/pages/index/product", 204 "app_path" : "https://www.example.com/jump-to-app", 205 "usage_description" : "全场可用", 206 "coupon_available_store_info" : { 207 "description" : "可在上海市区的所有门店使用,详细列表参考小程序内信息为准", 208 "mini_program_appid" : "wx1234567890", 209 "mini_program_path" : "/pages/index/store-list" 210 } 211 }, 212 "coupon_display_info" : { 213 "code_display_mode" : "QRCODE", 214 "background_color" : "Color010", 215 "entrance_mini_program" : { 216 "appid" : "wx1234567890", 217 "path" : "/pages/index/product", 218 "entrance_wording" : "欢迎选购", 219 "guidance_wording" : "获取更多优惠" 220 }, 221 "entrance_official_account" : { 222 "appid" : "wx1234567890" 223 }, 224 "entrance_finder" : { 225 "finder_id" : "gh_12345678", 226 "finder_video_id" : "UDFsdf24df34dD456Hdf34", 227 "finder_video_cover_image_url" : "https://wxpaylogo.qpic.cn/wxpaylogo/xxxxx/xxx" 228 } 229 }, 230 "notify_config" : { 231 "notify_appid" : "wx4fd12345678" 232 }, 233 "store_scope" : "SPECIFIC", 234 "sent_count_info" : { 235 "total_count" : 100, 236 "today_count" : 10 237 }, 238 "state" : "SENDING", 239 "deactivate_request_no" : "1002600620019090123143254436", 240 "deactivate_time" : "2025-01-01T00:00+08:00", 241 "deactivate_reason" : "批次信息有误,重新创建", 242 "brand_id" : "120344" 243 }, 244 "attach" : "example_attach", 245 "channel_custom_info" : "example_channel_custom_info", 246 "brand_id" : "120344", 247 "coupon_tag_info" : { 248 "coupon_tag_list" : [ 249 "MEMBER" 250 ], 251 "member_tag_info" : { 252 "member_card_id" : "MemberCardId_1234567890" 253 } 254 } 255 } 256 ], 257 "next_page_token" : "MTIzNDUK" 258} 259
错误码
以下是本接口返回的错误码列表。详细错误码规则,请参考微信支付接口规则-错误码和错误提示
状态码 | 错误码 | 描述 | 解决方案 |
|---|---|---|---|
400 | PARAM_ERROR | 参数错误 | 请根据错误提示正确传入参数 |
400 | INVALID_REQUEST | HTTP 请求不符合微信支付 APIv3 接口规则 | 请参阅 接口规则 |
401 | SIGN_ERROR | 验证不通过 | 请参阅 签名常见问题 |
500 | SYSTEM_ERROR | 系统异常,请稍后重试 | 请稍后重试 |
400 | INVALID_REQUEST | 传入参数不符合业务规则 | 请参考文档中对每个字段的要求以及组合要求,确认请求参数是否满足 |
404 | NOT_FOUND | 未找到 product_coupon_id 对应的商品券 | 请确认 product_coupon_id 存在且属于当前品牌 |
404 | NOT_FOUND | 未找到 stock_id 对应的商品券批次 | 请确认 stock_id 存在且属于当前商品券 |
429 | RATELIMIT_EXCEEDED | 请求超过接口频率限制 | 请稍后使用原参数重试 |

