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

