查询商家券批次详情

更新时间：2024.11.18

商户可通过该接口查询已创建的商家券批次详情信息。

接口说明

支持商户：【普通服务商】　【渠道商】

请求方式：【GET】/v3/marketing/busifavor/stocks/{stock_id}

请求域名：【主域名】https://api.mch.weixin.qq.com 使用该域名将访问就近的接入点

　　　　　【备域名】https://api2.mch.weixin.qq.com 使用该域名将访问异地的接入点，指引点击查看

请求参数

Header HTTP头参数

Authorization 　必填　string

请参考签名认证生成认证信息

Accept 　必填　string

请设置为application/json

path 路径参数

stock_id 　必填 string

【批次号】微信为每个商家券批次分配的唯一ID

请求示例

GET

1curl -X GET \
2  https://api.mch.weixin.qq.com/v3/marketing/busifavor/stocks/100088 \
3  -H "Authorization: WECHATPAY2-SHA256-RSA2048 mchid=\"1900000001\",..." \
4  -H "Accept: application/json" 
5

应答参数

200 OK

stock_name 　必填 string

【商家券批次名称】批次名称，字数上限为21个，一个中文汉字/英文字母/数字均占用一个字数。

belong_merchant 　必填 string

【批次归属商户号】批次是归属于哪个商户
注：
普通直连模式，该参数为直连商户号；
服务商模式，该参数为子商户号；
间连模式，该参数为子商户号。

comment 　选填 string

【批次备注】仅配置商户可见，用于自定义信息。字数上限为20个，一个中文汉字/英文字母/数字均占用一个字数。

goods_name 　必填 string

【适应商品范围】用来描述批次在哪些商品可用，会显示在微信卡包中。字数上限为15个，一个中文汉字/英文字母/数字均占用一个字数。

stock_type 　必填 string

【批次类型】批次类型

可选取值：：

NORMAL: 固定面额满减券批次
DISCOUNT: 折扣券批次
EXCHANGE: 换购券批次

coupon_use_rule 　必填 object

【核销规则】核销规则

属性

coupon_available_time 　必填 object

【券可核销时间】日期区间内可以使用优惠

属性

available_begin_time 　必填 string

【开始时间】批次开始时间，遵循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秒。
注意：商家券有效期最长为1年。

available_end_time 　必填 string

【结束时间】批次结束时间，遵循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秒。
注意：商家券有效期最长为1年。

available_day_after_receive 　选填 integer

【生效后N天内有效】日期区间内，券生效后x天内有效。例如生效当天内有效填1，生效后2天内有效填2，以此类推……注意，用户在有效期开始前领取商家券，则从有效期第1天开始计算天数，用户在有效期内领取商家券，则从领取当天开始计算天数，无论用户何时领取商家券，商家券在活动有效期结束后均不可用。可配合wait_days_after_receive一同填写，也可单独填写。单独填写时，有效期内领券后立即生效，生效后x天内有效。

available_week 　选填 object

【固定周期有效时间段】可以设置多个星期下的多个可用时间段，比如每周二10点到18点

属性

irregulary_avaliable_time 　选填 array[object]

【无规律的有效时间段】无规律的有效时间，多个无规律时间段

属性

wait_days_after_receive 　选填 integer

【领取后N天开始生效】日期区间内，用户领券后需等待x天开始生效。例如领券后当天开始生效则无需填写，领券后第2天开始生效填1，以此类推……用户在有效期开始前领取商家券，则从有效期第1天开始计算天数，用户在有效期内领取商家券，则从领取当天开始计算天数。无论用户何时领取商家券，商家券在活动有效期结束后均不可用。需配合available_day_after_receive一同填写，不可单独填写。注：最大不能超过30天

fixed_normal_coupon 　选填 object

【固定面额满减券使用规则】固定面额满减，折扣券，换购券使用规则三选一，stock_type为NORMAL时必填。

属性

discount_coupon 　选填 object

【折扣券使用规则】固定面额满减，折扣券，换购券使用规则三选一，stock_type为DISCOUNT时必填。

属性

exchange_coupon 　选填 object

【换购券使用规则】固定面额满减，折扣券，换购券使用规则三选一，stock_type为EXCHANGE时必填。

属性

use_method 　必填 string

【核销方式】核销方式

可选取值：：

OFF_LINE: 线下滴码核销，点击券“立即使用”跳转展示券二维码详情。
MINI_PROGRAMS: 线上小程序核销，点击券“立即使用”跳转至配置的商家小程序（需要添加小程序AppID和path）。
SELF_CONSUME: 微信支付付款码核销，点击券“立即使用”跳转至微信支付钱包付款码。
PAYMENT_CODE: 用户自助核销，点击券“立即使用”跳转至用户自助操作核销界面（当前暂不支持用户自助核销）。

mini_programs_appid 　选填 string

【小程序AppID】核销方式为线上小程序核销才有效

mini_programs_path 　选填 string

【小程序path】核销方式为线上小程序核销才有效

stock_send_rule 　必填 object

【发放规则】发放规则

属性

custom_entrance 　选填 object

【自定义入口】卡详情页面，可选择多种入口引导用户

属性

mini_programs_info 　选填 object

【小程序入口】需要小程序APPID、path、入口文案、引导文案。如果需要跳转小程序，APPID、path、入口文案为必填，引导文案非必填。
AppID要与归属商户号有M-A or M-m-suba关系。
注：请查看绑定关系说明文档

属性

appid 　选填 string

【商户公众号AppID】可配置商户公众号，从券详情可跳转至公众号，用户自定义字段。
校验规则：传入的AppID得是与调用方商户号（即请求头里面的商户号）有绑定关系的AppID 或传入的AppID得是归属商户号有绑定关系的AppID

hall_id 　选填 string

【更多优惠入口；营销馆创建地址：https://pay.weixin.qq.com/index.php/xphp/cfav_market/hall#/pages/list/list】填写微信支付营销馆的馆ID，用户自定义字段。营销馆需在商户平台创建。

store_id 　选填 string

【可用门店ID】填写代金券可用门店ID

code_display_mode 　选填 string

【code展示模式】code展示模式

可选取值：：

NOT_SHOW: 不展示code
BARCODE: 一维码
QRCODE: 二维码

display_pattern_info 　选填 object

【样式信息】创建批次时的样式信息

属性

description 　选填 string(1000)

【使用须知】用于说明详细的活动规则，会展示在代金券详情页。

merchant_logo_url 　选填 string

【商户logo】 若券归属商户号有认证品牌，则系统将自动拉取对应品牌logo；若券归属商户号不在认证品牌下，需自定义上传logo，未上传时将展示兜底灰色logo样式，影响券详情页用户体验，请及时上传。

商户logo的URL地址，仅支持通过《图片上传API》接口获取的图片URL地址。

1、商户logo大小需为120像素*120像素。

2、支持JPG/JPEG/PNG格式，且图片小于1M。

注：该字段暂不支持修改

merchant_name 　选填 string(16)

【商户名称】不支持商户自定义。若券归属商户号有认证品牌，系统将自动拉取认证品牌号下的品牌名称；若券归属商户号不在认证品牌下，则拉取本商户号的商户简称。展示上限12个字符。
注：该字段暂不支持修改

background_color 　选填 string

【背景颜色】券的背景颜色，可设置10种颜色，色值请参考下方说明。颜色取值为颜色图中的颜色名称。

coupon_image_url 　选填 string

【券详情图片】 券详情图片，1074像素（宽）*603像素（高），图片大小不超过2M，支持JPG/PNG格式。仅支持通过《图片上传API》接口获取的图片URL地址。

finder_info 　选填 object

【视频号相关信息】视频号相关信息

属性

stock_state 　必填 string

【批次状态】批次状态

可选取值：：

UNAUDIT: 审核中
RUNNING: 运行中
STOPED: 已停止
PAUSED: 暂停发放

coupon_code_mode 　必填 string

【券code模式】券code模式

可选取值：：

WECHATPAY_MODE: 系统分配code，商户无需额外操作
MERCHANT_API: 商户发放时接口指定券code
MERCHANT_UPLOAD: 商户上传自定义code，发券时系统随机选取上传的券code

stock_id 　必填 string

【批次号】批次唯一标识

coupon_code_count 　选填 object

【券code数量】当且仅当coupon_code_mode(券code模式)为MERCHANT_UPLOAD(商户上传自定义code)模式时，返回该字段；返回内容为商户上传code的数量信息

属性

notify_config 　选填 object

【事件通知配置】事件回调通知商户的配置

	属性
	notify_appid 　选填 string(64) 【事件通知AppID】用于回调通知时，计算返回操作用户的OpenID（诸如领券用户），支持小程序or公众号的AppID；如该字段不填写，则回调通知中涉及到用户身份信息的OpenID与UnionID都将为空。

send_count_information 　选填 object

【批次发放情况】批次发放情况

属性

subsidy 　选填 boolean

【是否允许营销补差】该批次发放的券是否允许进行补差
注：该字段暂未开放

应答示例

200 OK

1{
2  "stock_name" : "8月1日活动券",
3  "belong_merchant" : "10000022",
4  "comment" : "xxx店使用",
5  "goods_name" : "xxx商品使用",
6  "stock_type" : "NORMAL",
7  "coupon_use_rule" : {
8    "coupon_available_time" : {
9      "available_begin_time" : "2015-05-20T13:29:35+08:00",
10      "available_end_time" : "2015-05-20T13:29:35+08:00",
11      "available_day_after_receive" : 3,
12      "available_week" : {
13        "week_day" : [
14          1
15        ],
16        "available_day_time" : [
17          {
18            "begin_time" : 3600,
19            "end_time" : 86399
20          }
21        ]
22      },
23      "irregulary_avaliable_time" : [
24        {
25          "begin_time" : "2015-05-20T13:29:35+08:00",
26          "end_time" : "2015-05-20T13:29:35+08:00"
27        }
28      ],
29      "wait_days_after_receive" : 7
30    },
31    "fixed_normal_coupon" : {
32      "discount_amount" : 5,
33      "transaction_minimum" : 100
34    },
35    "discount_coupon" : {
36      "discount_percent" : 88,
37      "transaction_minimum" : 100
38    },
39    "exchange_coupon" : {
40      "exchange_price" : 100,
41      "transaction_minimum" : 100
42    },
43    "use_method" : "OFF_LINE",
44    "mini_programs_appid" : "wx23232232323",
45    "mini_programs_path" : "/path/index/index"
46  },
47  "stock_send_rule" : {
48    "max_amount" : 100000,
49    "max_coupons" : 100,
50    "max_coupons_per_user" : 5,
51    "max_amount_by_day" : 1000,
52    "max_coupons_by_day" : 100,
53    "natural_person_limit" : false,
54    "prevent_api_abuse" : false,
55    "transferable" : false,
56    "shareable" : false
57  },
58  "custom_entrance" : {
59    "mini_programs_info" : {
60      "mini_programs_appid" : "wx234545656765876",
61      "mini_programs_path" : "/path/index/index",
62      "entrance_words" : "欢迎选购",
63      "guiding_words" : "获取更多优惠"
64    },
65    "appid" : "wx324345hgfhfghfg",
66    "hall_id" : "233455656",
67    "store_id" : "233554655",
68    "code_display_mode" : "NOT_SHOW"
69  },
70  "display_pattern_info" : {
71    "description" : "xxx门店可用",
72    "merchant_logo_url" : "https://xxx",
73    "merchant_name" : "微信支付",
74    "background_color" : "xxxxx",
75    "coupon_image_url" : "图片cdn地址",
76    "finder_info" : {
77      "finder_id" : "sph6Rngt2T4RlUf",
78      "finder_video_id" : "export/UzFfAgtgekIEAQAAAAAAb4MgnPInmAAAAAstQy6ubaLX4KHWvLEZgBPEwIEgVnk9HIP-zNPgMJofG6tpdGPJNg_ojtEjoT94",
79      "finder_video_cover_image_url" : "https://wxpaylogo.qpic.cn/xxx"
80    }
81  },
82  "stock_state" : "UNAUDIT",
83  "coupon_code_mode" : "WECHATPAY_MODE",
84  "stock_id" : "1212",
85  "coupon_code_count" : {
86    "total_count" : 100,
87    "available_count" : 50
88  },
89  "notify_config" : {
90    "notify_appid" : "wx23232232323"
91  },
92  "send_count_information" : {
93    "total_send_num" : 1,
94    "total_send_amount" : 34,
95    "today_send_num" : 1,
96    "today_send_amount" : 34
97  },
98  "subsidy" : false
99}
100

错误码

公共错误码

状态码	错误码	描述	解决方案
400	PARAM_ERROR	参数错误	请根据错误提示正确传入参数
400	INVALID_REQUEST	HTTP 请求不符合微信支付 APIv3 接口规则	请参阅接口规则
401	SIGN_ERROR	验证不通过	请参阅签名常见问题
500	SYSTEM_ERROR	系统异常，请稍后重试	请稍后重试

业务错误码

状态码	错误码	描述	解决方案
400	APPID_MCHID_NOT_MATCH	AppID与请求方商户无关联关系	AppID与请求方商户不匹配，请确认AppID与请求方商户是否有关联关系
400	INVALID_REQUEST	发券模式不合法	请更换支持预上传code的批次后重试
400	INVALID_REQUEST	上传的自定义code已达上限	请更换一个新的批次后重试
400	MCH_NOT_EXISTS	商户号不存在	请确认传入的商户号是否正确
400	RESOURCE_ALREADY_EXISTS	批次已存在	查看out_request_no字段是否重复使用
400	RESOURCE_ALREADY_EXISTS	券已被其他订单核销	请通过查询券API确认券是否已被其他订单核销
400	SYSTEM_ERROR	系统错误	请使用相同参数稍后重新调用
403	NOAUTH	无权限	查看具体错误信息，确认是否有权限
403	RULELIMIT	券不在有效期	请确认券是否能在当前时间核销
404	RESOURCE_NOT_EXISTS	查询的资源不存在	请检查查询资源的对应ID是否填写正确
404	USER_NOT_EXISTS	OpenID不正确	请确认传入的OpenID是否正确
429	FREQUENCY_LIMITED	频率限制	调用太频繁，请降低调用接口频率
500	SYSTEM_ERROR	系统失败	多为网络超时引起，重试

文档是否有帮助

更多支持

开发文档(商户)开发文档(V2版)开发者社区微信开放平台微信公众平台腾讯客服