修改商品券
更新时间:2025.08.20品牌方可以通过该接口修改商品券信息。
注:修改只会对新发的券生效,历史已经发放给用户的券不会改变。
前置条件:商品券处于 EFFECTIVE 状态
频率限制:20/s
接口说明
支持商户:【品牌商户】
请求方式:【PATCH】/brand/marketing/product-coupon/product-coupons/{product_coupon_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
Wechatpay-Serial 必填 string
【微信支付公钥ID】 请传入brand_id对应的微信支付公钥ID,接口将会校验两者的关联关系,参考微信支付公钥产品简介及使用说明获取微信支付公钥ID和相关的介绍。以下两种场景将使用到微信支付公钥: 1、接收到接口的返回内容,需要使用微信支付公钥进行验签; 2、调用含有敏感信息参数(如姓名、身份证号码)的接口时,需要使用微信支付公钥加密敏感信息后再传输参数,加密指引请参考微信支付公钥加密敏感信息指引。
path 路径参数
product_coupon_id 必填 string
【商品券ID】 商品券的唯一标识,创建商品券时由微信支付生成
body 包体参数
out_request_no 必填 string(40)
【修改请求单号】 品牌修改商品券的请求流水号,品牌侧需保持唯一性,可使用 数字、大小写字母、下划线_、短横线- 组成,长度在6-40个字符之间
display_info 必填 object
【展示信息】 商品券展示信息
| 属性 | |||||||||
name 必填 string(15) 【商品券名称】 商品券名称,长度为3-15个UTF-8字符 image_url 必填 string 【商品券图片】 商品图片的链接地址,仅支持通过图片上传接口获取的图片URL地址。
background_url 必填 string 【商品券背景图】 商品背景图片的URL地址,仅支持通过图片上传接口获取的图片URL地址。
detail_image_url_list 选填 array[string] 【商品券详情图列表】 商品详情图URL地址列表,用于最多可上传8张图片,仅支持通过图片上传接口获取的图片URL地址。
original_price 选填 integer 【商品原价】 单位为分,当且仅当 combo_package_list 选填 array[object] 【套餐组合】 当
|
请求示例
PATCH
1curl -X PATCH \ 2 https://api.mch.weixin.qq.com/brand/marketing/product-coupon/product-coupons/200000001 \ 3 -H "Authorization: WECHATPAY-BRAND-SHA256-RSA2048 brand_id=\"XXXX\",..." \ 4 -H "Accept: application/json" \ 5 -H "Wechatpay-Serial: PUB_KEY_ID_XXXX" \ 6 -H "Content-Type: application/json" \ 7 -d '{ 8 "out_request_no" : "34657_20250101_123456", 9 "display_info" : { 10 "name" : "全场满100可减10元", 11 "image_url" : "https://wxpaylogo.qpic.cn/wxpaylogo/xxxxx/xxx", 12 "background_url" : "https://wxpaylogo.qpic.cn/wxpaylogo/xxxxx/xxx", 13 "detail_image_url_list" : [ 14 "https://wxpaylogo.qpic.cn/wxpaylogo/xxxxx/xxx" 15 ], 16 "original_price" : 10000, 17 "combo_package_list" : [ 18 { 19 "name" : "咖啡2选1", 20 "pick_count" : 3, 21 "choice_list" : [ 22 { 23 "name" : "美式", 24 "price" : 10000, 25 "count" : 2, 26 "image_url" : "https://wxpaylogo.qpic.cn/wxpaylogo/xxxxx/xxx", 27 "mini_program_appid" : "wx4fd12345678", 28 "mini_program_path" : "/pages/index/index" 29 } 30 ] 31 } 32 ] 33 } 34 }' 35
需配合微信支付工具库 WXPayUtility 使用,请参考Java
1package com.java.demo; 2 3import com.java.utils.WXPayBrandUtility; // 引用微信支付工具库,参考:https://pay.weixin.qq.com/doc/brand/4015826861 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 UpdateProductCoupon { 26 private static String HOST = "https://api.mch.weixin.qq.com"; 27 private static String METHOD = "PATCH"; 28 private static String PATH = "/brand/marketing/product-coupon/product-coupons/{product_coupon_id}"; 29 30 public static void main(String[] args) { 31 // TODO: 请准备商户开发必要参数,参考:https://pay.weixin.qq.com/doc/brand/4015415289 32 UpdateProductCoupon client = new UpdateProductCoupon( 33 "xxxxxxxx", // 品牌ID,是由微信支付系统生成并分配给每个品牌方的唯一标识符,品牌ID获取方式参考 https://pay.weixin.qq.com/doc/brand/4015415289 34 "1DDE55AD98Exxxxxxxxxx", // 品牌API证书序列号,如何获取请参考 https://pay.weixin.qq.com/doc/brand/4015407570 35 "/path/to/apiclient_key.pem", // 品牌API证书私钥文件路径,本地文件路径 36 "PUB_KEY_ID_xxxxxxxxxxxxx", // 微信支付公钥ID,如何获取请参考 https://pay.weixin.qq.com/doc/brand/4015453439 37 "/path/to/wxp_pub.pem" // 微信支付公钥文件路径,本地文件路径 38 ); 39 40 UpdateProductCouponRequest request = new UpdateProductCouponRequest(); 41 request.productCouponId = "200000001"; 42 request.outRequestNo = "34657_20250101_123456"; 43 request.displayInfo = new ProductCouponDisplayInfo(); 44 request.displayInfo.name = "全场满100可减10元"; 45 request.displayInfo.imageUrl = "https://wxpaylogo.qpic.cn/wxpaylogo/xxxxx/xxx"; 46 request.displayInfo.backgroundUrl = "https://wxpaylogo.qpic.cn/wxpaylogo/xxxxx/xxx"; 47 request.displayInfo.detailImageUrlList = new ArrayList<>(); 48 { 49 request.displayInfo.detailImageUrlList.add("https://wxpaylogo.qpic.cn/wxpaylogo/xxxxx/xxx"); 50 }; 51 request.displayInfo.originalPrice = 10000L; 52 request.displayInfo.comboPackageList = new ArrayList<>(); 53 { 54 ComboPackage comboPackageListItem = new ComboPackage(); 55 comboPackageListItem.name = "咖啡2选1"; 56 comboPackageListItem.pickCount = 3L; 57 comboPackageListItem.choiceList = new ArrayList<>(); 58 { 59 ComboPackageChoice choiceListItem = new ComboPackageChoice(); 60 choiceListItem.name = "美式"; 61 choiceListItem.price = 10000L; 62 choiceListItem.count = 2L; 63 choiceListItem.imageUrl = "https://wxpaylogo.qpic.cn/wxpaylogo/xxxxx/xxx"; 64 choiceListItem.miniProgramAppid = "wx4fd12345678"; 65 choiceListItem.miniProgramPath = "/pages/index/index"; 66 comboPackageListItem.choiceList.add(choiceListItem); 67 }; 68 request.displayInfo.comboPackageList.add(comboPackageListItem); 69 }; 70 try { 71 ProductCouponEntity response = client.run(request); 72 // TODO: 请求成功,继续业务逻辑 73 System.out.println(response); 74 } catch (WXPayBrandUtility.ApiException e) { 75 // TODO: 请求失败,根据状态码执行不同的逻辑 76 e.printStackTrace(); 77 } 78 } 79 80 public ProductCouponEntity run(UpdateProductCouponRequest request) { 81 String uri = PATH; 82 uri = uri.replace("{product_coupon_id}", WXPayBrandUtility.urlEncode(request.productCouponId)); 83 String reqBody = WXPayBrandUtility.toJson(request); 84 85 Request.Builder reqBuilder = new Request.Builder().url(HOST + uri); 86 reqBuilder.addHeader("Accept", "application/json"); 87 reqBuilder.addHeader("Wechatpay-Serial", wechatPayPublicKeyId); 88 reqBuilder.addHeader("Authorization", WXPayBrandUtility.buildAuthorization(brand_id, certificateSerialNo,privateKey, METHOD, uri, reqBody)); 89 reqBuilder.addHeader("Content-Type", "application/json"); 90 RequestBody requestBody = RequestBody.create(MediaType.parse("application/json; charset=utf-8"), reqBody); 91 reqBuilder.method(METHOD, requestBody); 92 Request httpRequest = reqBuilder.build(); 93 94 // 发送HTTP请求 95 OkHttpClient client = new OkHttpClient.Builder().build(); 96 try (Response httpResponse = client.newCall(httpRequest).execute()) { 97 String respBody = WXPayBrandUtility.extractBody(httpResponse); 98 if (httpResponse.code() >= 200 && httpResponse.code() < 300) { 99 // 2XX 成功,验证应答签名 100 WXPayBrandUtility.validateResponse(this.wechatPayPublicKeyId, this.wechatPayPublicKey, 101 httpResponse.headers(), respBody); 102 103 // 从HTTP应答报文构建返回数据 104 return WXPayBrandUtility.fromJson(respBody, ProductCouponEntity.class); 105 } else { 106 throw new WXPayBrandUtility.ApiException(httpResponse.code(), respBody, httpResponse.headers()); 107 } 108 } catch (IOException e) { 109 throw new UncheckedIOException("Sending request to " + uri + " failed.", e); 110 } 111 } 112 113 private final String brand_id; 114 private final String certificateSerialNo; 115 private final PrivateKey privateKey; 116 private final String wechatPayPublicKeyId; 117 private final PublicKey wechatPayPublicKey; 118 119 public UpdateProductCoupon(String brand_id, String certificateSerialNo, String privateKeyFilePath, String wechatPayPublicKeyId, String wechatPayPublicKeyFilePath) { 120 this.brand_id = brand_id; 121 this.certificateSerialNo = certificateSerialNo; 122 this.privateKey = WXPayBrandUtility.loadPrivateKeyFromPath(privateKeyFilePath); 123 this.wechatPayPublicKeyId = wechatPayPublicKeyId; 124 this.wechatPayPublicKey = WXPayBrandUtility.loadPublicKeyFromPath(wechatPayPublicKeyFilePath); 125 } 126 127 public static class UpdateProductCouponRequest { 128 @SerializedName("out_request_no") 129 public String outRequestNo; 130 131 @SerializedName("product_coupon_id") 132 @Expose(serialize = false) 133 public String productCouponId; 134 135 @SerializedName("display_info") 136 public ProductCouponDisplayInfo displayInfo; 137 } 138 139 public static class ProductCouponEntity { 140 @SerializedName("product_coupon_id") 141 public String productCouponId; 142 143 @SerializedName("scope") 144 public ProductCouponScope scope; 145 146 @SerializedName("type") 147 public ProductCouponType type; 148 149 @SerializedName("usage_mode") 150 public UsageMode usageMode; 151 152 @SerializedName("single_usage_info") 153 public SingleUsageInfo singleUsageInfo; 154 155 @SerializedName("sequential_usage_info") 156 public SequentialUsageInfo sequentialUsageInfo; 157 158 @SerializedName("display_info") 159 public ProductCouponDisplayInfo displayInfo; 160 161 @SerializedName("out_product_no") 162 public String outProductNo; 163 164 @SerializedName("state") 165 public ProductCouponState state; 166 167 @SerializedName("deactivate_request_no") 168 public String deactivateRequestNo; 169 170 @SerializedName("deactivate_time") 171 public String deactivateTime; 172 173 @SerializedName("deactivate_reason") 174 public String deactivateReason; 175 } 176 177 public static class ProductCouponDisplayInfo { 178 @SerializedName("name") 179 public String name; 180 181 @SerializedName("image_url") 182 public String imageUrl; 183 184 @SerializedName("background_url") 185 public String backgroundUrl; 186 187 @SerializedName("detail_image_url_list") 188 public List<String> detailImageUrlList; 189 190 @SerializedName("original_price") 191 public Long originalPrice; 192 193 @SerializedName("combo_package_list") 194 public List<ComboPackage> comboPackageList; 195 } 196 197 public enum ProductCouponScope { 198 @SerializedName("ALL") 199 ALL, 200 @SerializedName("SINGLE") 201 SINGLE 202 } 203 204 public enum ProductCouponType { 205 @SerializedName("NORMAL") 206 NORMAL, 207 @SerializedName("DISCOUNT") 208 DISCOUNT, 209 @SerializedName("EXCHANGE") 210 EXCHANGE 211 } 212 213 public enum UsageMode { 214 @SerializedName("SINGLE") 215 SINGLE, 216 @SerializedName("SEQUENTIAL") 217 SEQUENTIAL 218 } 219 220 public static class SingleUsageInfo { 221 @SerializedName("normal_coupon") 222 public NormalCouponUsageRule normalCoupon; 223 224 @SerializedName("discount_coupon") 225 public DiscountCouponUsageRule discountCoupon; 226 } 227 228 public static class SequentialUsageInfo { 229 @SerializedName("type") 230 public SequentialUsageType type; 231 232 @SerializedName("count") 233 public Long count; 234 235 @SerializedName("available_days") 236 public Long availableDays; 237 238 @SerializedName("interval_days") 239 public Long intervalDays; 240 } 241 242 public enum ProductCouponState { 243 @SerializedName("AUDITING") 244 AUDITING, 245 @SerializedName("EFFECTIVE") 246 EFFECTIVE, 247 @SerializedName("DEACTIVATED") 248 DEACTIVATED 249 } 250 251 public static class ComboPackage { 252 @SerializedName("name") 253 public String name; 254 255 @SerializedName("pick_count") 256 public Long pickCount; 257 258 @SerializedName("choice_list") 259 public List<ComboPackageChoice> choiceList = new ArrayList<ComboPackageChoice>(); 260 } 261 262 public static class NormalCouponUsageRule { 263 @SerializedName("threshold") 264 public Long threshold; 265 266 @SerializedName("discount_amount") 267 public Long discountAmount; 268 } 269 270 public static class DiscountCouponUsageRule { 271 @SerializedName("threshold") 272 public Long threshold; 273 274 @SerializedName("percent_off") 275 public Long percentOff; 276 } 277 278 public enum SequentialUsageType { 279 @SerializedName("INCREMENTAL") 280 INCREMENTAL, 281 @SerializedName("EQUAL") 282 EQUAL 283 } 284 285 public static class ComboPackageChoice { 286 @SerializedName("name") 287 public String name; 288 289 @SerializedName("price") 290 public Long price; 291 292 @SerializedName("count") 293 public Long count; 294 295 @SerializedName("image_url") 296 public String imageUrl; 297 298 @SerializedName("mini_program_appid") 299 public String miniProgramAppid; 300 301 @SerializedName("mini_program_path") 302 public String miniProgramPath; 303 } 304 305} 306
需配合微信支付工具库 wxpay_utility 使用,请参考Go
1package main 2 3import ( 4 "bytes" 5 "demo/wxpay_brand_utility" // 引用微信支付工具库,参考 https://pay.weixin.qq.com/doc/brand/4015826866 6 "encoding/json" 7 "fmt" 8 "net/http" 9 "net/url" 10 "strings" 11) 12 13func main() { 14 // TODO: 请准备商户开发必要参数,参考:https://pay.weixin.qq.com/doc/brand/4015415289 15 config, err := wxpay_brand_utility.CreateBrandConfig( 16 "xxxxxxxx", // 品牌ID,是由微信支付系统生成并分配给每个品牌方的唯一标识符,品牌ID获取方式参考 https://pay.weixin.qq.com/doc/brand/4015415289 17 "1DDE55AD98Exxxxxxxxxx", // 品牌API证书序列号,如何获取请参考 https://pay.weixin.qq.com/doc/brand/4015407570 18 "/path/to/apiclient_key.pem", // 品牌API证书私钥文件路径,本地文件路径 19 "PUB_KEY_ID_xxxxxxxxxxxxx", // 微信支付公钥ID,如何获取请参考 https://pay.weixin.qq.com/doc/brand/4015453439 20 "/path/to/wxp_pub.pem", // 微信支付公钥文件路径,本地文件路径 21 ) 22 if err != nil { 23 fmt.Println(err) 24 return 25 } 26 27 request := &UpdateProductCouponRequest{ 28 ProductCouponId: wxpay_brand_utility.String("200000001"), 29 OutRequestNo: wxpay_brand_utility.String("34657_20250101_123456"), 30 DisplayInfo: &ProductCouponDisplayInfo{ 31 Name: wxpay_brand_utility.String("全场满100可减10元"), 32 ImageUrl: wxpay_brand_utility.String("https://wxpaylogo.qpic.cn/wxpaylogo/xxxxx/xxx"), 33 BackgroundUrl: wxpay_brand_utility.String("https://wxpaylogo.qpic.cn/wxpaylogo/xxxxx/xxx"), 34 DetailImageUrlList: []string{"https://wxpaylogo.qpic.cn/wxpaylogo/xxxxx/xxx"}, 35 OriginalPrice: wxpay_brand_utility.Int64(10000), 36 ComboPackageList: []ComboPackage{ComboPackage{ 37 Name: wxpay_brand_utility.String("咖啡2选1"), 38 PickCount: wxpay_brand_utility.Int64(3), 39 ChoiceList: []ComboPackageChoice{ComboPackageChoice{ 40 Name: wxpay_brand_utility.String("美式"), 41 Price: wxpay_brand_utility.Int64(10000), 42 Count: wxpay_brand_utility.Int64(2), 43 ImageUrl: wxpay_brand_utility.String("https://wxpaylogo.qpic.cn/wxpaylogo/xxxxx/xxx"), 44 MiniProgramAppid: wxpay_brand_utility.String("wx4fd12345678"), 45 MiniProgramPath: wxpay_brand_utility.String("/pages/index/index"), 46 }}, 47 }}, 48 }, 49 } 50 51 response, err := UpdateProductCoupon(config, request) 52 if err != nil { 53 fmt.Printf("请求失败: %+v\n", err) 54 // TODO: 请求失败,根据状态码执行不同的处理 55 return 56 } 57 58 // TODO: 请求成功,继续业务逻辑 59 fmt.Printf("请求成功: %+v\n", response) 60} 61 62func UpdateProductCoupon(config *wxpay_brand_utility.BrandConfig, request *UpdateProductCouponRequest) (response *ProductCouponEntity, err error) { 63 const ( 64 host = "https://api.mch.weixin.qq.com" 65 method = "PATCH" 66 path = "/brand/marketing/product-coupon/product-coupons/{product_coupon_id}" 67 ) 68 69 reqUrl, err := url.Parse(fmt.Sprintf("%s%s", host, path)) 70 if err != nil { 71 return nil, err 72 } 73 reqUrl.Path = strings.Replace(reqUrl.Path, "{product_coupon_id}", url.PathEscape(*request.ProductCouponId), -1) 74 reqBody, err := json.Marshal(request) 75 if err != nil { 76 return nil, err 77 } 78 httpRequest, err := http.NewRequest(method, reqUrl.String(), bytes.NewReader(reqBody)) 79 if err != nil { 80 return nil, err 81 } 82 httpRequest.Header.Set("Accept", "application/json") 83 httpRequest.Header.Set("Wechatpay-Serial", config.WechatPayPublicKeyId()) 84 httpRequest.Header.Set("Content-Type", "application/json") 85 authorization, err := wxpay_brand_utility.BuildAuthorization(config.BrandId(), config.CertificateSerialNo(), config.PrivateKey(), method, reqUrl.RequestURI(), reqBody) 86 if err != nil { 87 return nil, err 88 } 89 httpRequest.Header.Set("Authorization", authorization) 90 91 client := &http.Client{} 92 httpResponse, err := client.Do(httpRequest) 93 if err != nil { 94 return nil, err 95 } 96 respBody, err := wxpay_brand_utility.ExtractResponseBody(httpResponse) 97 if err != nil { 98 return nil, err 99 } 100 if httpResponse.StatusCode >= 200 && httpResponse.StatusCode < 300 { 101 // 2XX 成功,验证应答签名 102 err = wxpay_brand_utility.ValidateResponse( 103 config.WechatPayPublicKeyId(), 104 config.WechatPayPublicKey(), 105 &httpResponse.Header, 106 respBody, 107 ) 108 if err != nil { 109 return nil, err 110 } 111 response := &ProductCouponEntity{} 112 if err := json.Unmarshal(respBody, response); err != nil { 113 return nil, err 114 } 115 116 return response, nil 117 } else { 118 return nil, wxpay_brand_utility.NewApiException( 119 httpResponse.StatusCode, 120 httpResponse.Header, 121 respBody, 122 ) 123 } 124} 125 126type UpdateProductCouponRequest struct { 127 OutRequestNo *string `json:"out_request_no,omitempty"` 128 ProductCouponId *string `json:"product_coupon_id,omitempty"` 129 DisplayInfo *ProductCouponDisplayInfo `json:"display_info,omitempty"` 130} 131 132func (o *UpdateProductCouponRequest) MarshalJSON() ([]byte, error) { 133 type Alias UpdateProductCouponRequest 134 a := &struct { 135 ProductCouponId *string `json:"product_coupon_id,omitempty"` 136 *Alias 137 }{ 138 // 序列化时移除非 Body 字段 139 ProductCouponId: nil, 140 Alias: (*Alias)(o), 141 } 142 return json.Marshal(a) 143} 144 145type ProductCouponEntity struct { 146 ProductCouponId *string `json:"product_coupon_id,omitempty"` 147 Scope *ProductCouponScope `json:"scope,omitempty"` 148 Type *ProductCouponType `json:"type,omitempty"` 149 UsageMode *UsageMode `json:"usage_mode,omitempty"` 150 SingleUsageInfo *SingleUsageInfo `json:"single_usage_info,omitempty"` 151 SequentialUsageInfo *SequentialUsageInfo `json:"sequential_usage_info,omitempty"` 152 DisplayInfo *ProductCouponDisplayInfo `json:"display_info,omitempty"` 153 OutProductNo *string `json:"out_product_no,omitempty"` 154 State *ProductCouponState `json:"state,omitempty"` 155 DeactivateRequestNo *string `json:"deactivate_request_no,omitempty"` 156 DeactivateTime *string `json:"deactivate_time,omitempty"` 157 DeactivateReason *string `json:"deactivate_reason,omitempty"` 158} 159 160type ProductCouponDisplayInfo struct { 161 Name *string `json:"name,omitempty"` 162 ImageUrl *string `json:"image_url,omitempty"` 163 BackgroundUrl *string `json:"background_url,omitempty"` 164 DetailImageUrlList []string `json:"detail_image_url_list,omitempty"` 165 OriginalPrice *int64 `json:"original_price,omitempty"` 166 ComboPackageList []ComboPackage `json:"combo_package_list,omitempty"` 167} 168 169type ProductCouponScope string 170 171func (e ProductCouponScope) Ptr() *ProductCouponScope { 172 return &e 173} 174 175const ( 176 PRODUCTCOUPONSCOPE_ALL ProductCouponScope = "ALL" 177 PRODUCTCOUPONSCOPE_SINGLE ProductCouponScope = "SINGLE" 178) 179 180type ProductCouponType string 181 182func (e ProductCouponType) Ptr() *ProductCouponType { 183 return &e 184} 185 186const ( 187 PRODUCTCOUPONTYPE_NORMAL ProductCouponType = "NORMAL" 188 PRODUCTCOUPONTYPE_DISCOUNT ProductCouponType = "DISCOUNT" 189 PRODUCTCOUPONTYPE_EXCHANGE ProductCouponType = "EXCHANGE" 190) 191 192type UsageMode string 193 194func (e UsageMode) Ptr() *UsageMode { 195 return &e 196} 197 198const ( 199 USAGEMODE_SINGLE UsageMode = "SINGLE" 200 USAGEMODE_SEQUENTIAL UsageMode = "SEQUENTIAL" 201) 202 203type SingleUsageInfo struct { 204 NormalCoupon *NormalCouponUsageRule `json:"normal_coupon,omitempty"` 205 DiscountCoupon *DiscountCouponUsageRule `json:"discount_coupon,omitempty"` 206} 207 208type SequentialUsageInfo struct { 209 Type *SequentialUsageType `json:"type,omitempty"` 210 Count *int64 `json:"count,omitempty"` 211 AvailableDays *int64 `json:"available_days,omitempty"` 212 IntervalDays *int64 `json:"interval_days,omitempty"` 213} 214 215type ProductCouponState string 216 217func (e ProductCouponState) Ptr() *ProductCouponState { 218 return &e 219} 220 221const ( 222 PRODUCTCOUPONSTATE_AUDITING ProductCouponState = "AUDITING" 223 PRODUCTCOUPONSTATE_EFFECTIVE ProductCouponState = "EFFECTIVE" 224 PRODUCTCOUPONSTATE_DEACTIVATED ProductCouponState = "DEACTIVATED" 225) 226 227type ComboPackage struct { 228 Name *string `json:"name,omitempty"` 229 PickCount *int64 `json:"pick_count,omitempty"` 230 ChoiceList []ComboPackageChoice `json:"choice_list,omitempty"` 231} 232 233type NormalCouponUsageRule struct { 234 Threshold *int64 `json:"threshold,omitempty"` 235 DiscountAmount *int64 `json:"discount_amount,omitempty"` 236} 237 238type DiscountCouponUsageRule struct { 239 Threshold *int64 `json:"threshold,omitempty"` 240 PercentOff *int64 `json:"percent_off,omitempty"` 241} 242 243type SequentialUsageType string 244 245func (e SequentialUsageType) Ptr() *SequentialUsageType { 246 return &e 247} 248 249const ( 250 SEQUENTIALUSAGETYPE_INCREMENTAL SequentialUsageType = "INCREMENTAL" 251 SEQUENTIALUSAGETYPE_EQUAL SequentialUsageType = "EQUAL" 252) 253 254type ComboPackageChoice struct { 255 Name *string `json:"name,omitempty"` 256 Price *int64 `json:"price,omitempty"` 257 Count *int64 `json:"count,omitempty"` 258 ImageUrl *string `json:"image_url,omitempty"` 259 MiniProgramAppid *string `json:"mini_program_appid,omitempty"` 260 MiniProgramPath *string `json:"mini_program_path,omitempty"` 261} 262
应答参数
200 OK
product_coupon_id 必填 string(40)
【商品券ID】 商品券的唯一标识,由微信支付生成
scope 必填 string
【优惠范围】 商品券优惠范围
可选取值
ALL: 全场券,此时券类型type仅可配置为NORMAL或DISCOUNTSINGLE: 单品券,此时券类型type配置不受限制,即可配置为NORMAL、DISCOUNT或EXCHANGE
type 必填 string
【商品券类型】 商品券的优惠类型
可选取值
NORMAL: 满减券DISCOUNT: 折扣券EXCHANGE: 兑换券,仅在scope为SINGLE时可配置
usage_mode 必填 string
【使用模式】 商品券使用模式
可选取值
SINGLE: 单券,即用户只能使用一次,使用后券失效SEQUENTIAL: 多次优惠,即用户可以按顺序多次使用,每次核销成功后会发放下一次优惠机会,直到用完为止
single_usage_info 选填 object
【单券模式信息】 单券模式配置信息,当且仅当 usage_mode 为 SINGLE 时提供,其他场景不提供。
| 属性 | |||||||||
normal_coupon 选填 object 【满减券使用规则】 本商品券内所有批次均以此规则提供满减优惠,当且仅当
discount_coupon 选填 object 【折扣券使用规则】 本商品券内所有批次均以此规则提供折扣优惠,当且仅当
|
sequential_usage_info 选填 object
【多次优惠模式信息】 多次优惠模式配置信息,当且仅当 usage_mode 为 SEQUENTIAL 时提供,其他模式不提供。
| 属性 | |
type 必填 string 【多次优惠规则类型】 多次优惠规则类型 可选取值
count 必填 integer 【可使用次数】 本多次优惠领取后用户可使用次数,最多15次 available_days 必填 integer 【多次优惠有效天数】 用户的多次优惠生效后 N 天内有效,最少3天,最多365天 interval_days 选填 integer 【多次优惠使用间隔天数】 多次优惠多次使用之间需要间隔的天数,最高7天。例如:
默认情况下为 |
display_info 必填 object
【展示信息】 商品券展示信息
| 属性 | |||||||||
name 必填 string(15) 【商品券名称】 商品券名称,长度为3-15个UTF-8字符 image_url 必填 string 【商品券图片】 商品图片的链接地址,仅支持通过图片上传接口获取的图片URL地址。
background_url 必填 string 【商品券背景图】 商品背景图片的URL地址,仅支持通过图片上传接口获取的图片URL地址。
detail_image_url_list 选填 array[string] 【商品券详情图列表】 商品详情图URL地址列表,用于最多可上传8张图片,仅支持通过图片上传接口获取的图片URL地址。
original_price 选填 integer 【商品原价】 单位为分,当且仅当 combo_package_list 选填 array[object] 【套餐组合】 当
|
out_product_no 选填 string
【外部商品ID】 商户创建商品券时主动传入的外部商品ID,原样返回
state 必填 string
【商品券状态】 商品券状态
可选取值
AUDITING: 审批中,审批完成前商品券不可用EFFECTIVE: 生效中,商品券已生效,可以正常使用DEACTIVATED: 已失效,品牌方主动调用失效接口使商品券失效
deactivate_request_no 选填 string
【失效请求单号】 当且仅当 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
【失效原因】 当且仅当 state 为 DEACTIVATED 时提供,返回品牌方调用失效商品券接口时传入的失效原因
应答示例
200 OK
1{ 2 "product_coupon_id" : "1002323", 3 "scope" : "ALL", 4 "type" : "NORMAL", 5 "usage_mode" : "SEQUENTIAL", 6 "single_usage_info" : { 7 "normal_coupon" : { 8 "threshold" : 10000, 9 "discount_amount" : 100 10 }, 11 "discount_coupon" : { 12 "threshold" : 10000, 13 "percent_off" : 30 14 } 15 }, 16 "sequential_usage_info" : { 17 "type" : "EQUAL", 18 "count" : 10, 19 "available_days" : 10, 20 "interval_days" : 1 21 }, 22 "display_info" : { 23 "name" : "全场满100可减10元", 24 "image_url" : "https://wxpaylogo.qpic.cn/wxpaylogo/xxxxx/xxx", 25 "background_url" : "https://wxpaylogo.qpic.cn/wxpaylogo/xxxxx/xxx", 26 "detail_image_url_list" : [ 27 "https://wxpaylogo.qpic.cn/wxpaylogo/xxxxx/xxx" 28 ], 29 "original_price" : 10000, 30 "combo_package_list" : [ 31 { 32 "name" : "咖啡2选1", 33 "pick_count" : 3, 34 "choice_list" : [ 35 { 36 "name" : "美式", 37 "price" : 10000, 38 "count" : 2, 39 "image_url" : "https://wxpaylogo.qpic.cn/wxpaylogo/xxxxx/xxx", 40 "mini_program_appid" : "wx4fd12345678", 41 "mini_program_path" : "/pages/index/index" 42 } 43 ] 44 } 45 ] 46 }, 47 "out_product_no" : "Product_1234567890", 48 "state" : "AUDITING", 49 "deactivate_request_no" : "1002600620019090123143254436", 50 "deactivate_time" : "2025-06-20T13:29:35+08:00", 51 "deactivate_reason" : "商品已下架" 52} 53
错误码
以下是本接口返回的错误码列表。详细错误码规则,请参考微信支付接口规则-错误码和错误提示
状态码 | 错误码 | 描述 | 解决方案 |
|---|---|---|---|
400 | PARAM_ERROR | 参数错误 | 请根据错误提示正确传入参数 |
400 | INVALID_REQUEST | HTTP 请求不符合微信支付 APIv3 接口规则 | 请参阅 接口规则 |
401 | SIGN_ERROR | 验证不通过 | 请参阅 签名常见问题 |
500 | SYSTEM_ERROR | 系统异常,请稍后重试 | 请稍后重试 |
400 | INVALID_REQUEST | 单券使用模式的商品券批次,应该在「单券使用规则」中包含对应类型的优惠规则。对于文档中标记不应填写的优惠规则应删除。 | 请在「单券使用规则」中包含对应类型的优惠规则,并删除文档中标记不应填写的优惠规则。 |
400 | INVALID_REQUEST | 多次优惠使用模式的商品券批次,应该在「多次优惠使用规则」中包含对应类型的优惠规则,且数量与多次优惠的优惠次数相等 | 在「多次优惠使用规则」中包含对应类型的优惠规则,且数量与多次优惠的优惠次数相等 |
400 | INVALID_REQUEST | 单品满减券或单品折扣券不应在商品券中设置「满减券使用规则」或「折扣券使用规则」,而是应该在商品券批次中设置 | 请删除商品券中的「满减券使用规则」或「折扣券使用规则」,并在商品券批次中设置对应的优惠规则 |
403 | NO_AUTH | 品牌没有此接口权限 | 品牌没有此接口权限 |
400 | INVALID_REQUEST | 商品券支持APP核销时,必须提供「APP跳转路径」 | 请提供「APP跳转路径」参数 |
400 | PARAM_ERROR | 分页大小超出限制,请根据接口文档调整到允许的范围 | 请调整分页大小到规定范围 |
400 | INVALID_REQUEST | 商品券支持小程序核销时,必须提供「小程序AppID」 | 请提供「小程序AppID」 |
400 | INVALID_REQUEST | 单品券必须提供商品原价,请补充 | 请补充商品原价 |
400 | INVALID_REQUEST | 商品券支持小程序核销时,必须提供「小程序跳转路径」 | 请提供提供「小程序跳转路径」 |
400 | INVALID_REQUEST | 单品券必须提供商品券套餐组合信息,请补充 | 请提供商品券套餐组合信息 |
400 | PARAM_ERROR | 时间字符串格式错误,请使用 RFC3339 标准格式 | 请使用 RFC3339 标准格式 |
400 | INVALID_REQUEST | 单券模式下,全场折扣券应在商品券中提供折扣券使用规则信息 | 请在商品券中提供「折扣券使用规则信息」 |
400 | INVALID_REQUEST | 单券模式下,全场满减券应在商品券中提供满减券使用规则信息 | 请在商品券中提供「满减券使用规则信息」 |
400 | INVALID_REQUEST | 每周固定可用时间(weekly_available_period)中提供当天可用时间段时(day_period_list),每周可用星期数(day_list)必填 | 请补充 每周可用星期数(day_list) |
400 | INVALID_REQUEST | 单券模式下,全场券需要提供「单券模式信息(single_usage_info)」 | 请提供单券模式信息(single_usage_info) |
400 | INVALID_REQUEST | 多次优惠模式下必须提供「多次优惠模式信息(sequential_usage_info)」 | 请填写 多次优惠模式信息(sequential_usage_info) |
400 | INVALID_REQUEST | 传入的OpenID不合法 | 请使用参数 AppID 对应的的OpenID |

