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

