查询商家券批次详情

更新时间:2024.09.20

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

接口说明

支持商户:【普通商户】

请求方式:【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

请求示例

curl
Java
Go

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点

属性

 week_day  选填   array[integer]

【可用星期数】0代表周日,1代表周一,以此类推 当填写available_day_time时,week_day必填


 available_day_time  选填   array[object]

【当天可用时间段】可以填写多个时间段,最多不超过2个

属性

 begin_time  选填   integer

【当天可用开始时间】当天可用开始时间 单位秒 1代表当天0点0分1秒


 end_time  选填   integer

【当天可用结束时间】当天可用结束时间 单位秒 86399代表当天23点59分59秒


 irregulary_avaliable_time  选填   array[object]

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

属性

 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秒。


 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秒。


 wait_days_after_receive  选填   integer

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


 fixed_normal_coupon  选填   object

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

属性

 discount_amount  选填   integer

【优惠金额】优惠金额 单位分。
特殊规则:取值范围 1 ≤ value ≤ 10000000


 transaction_minimum  选填   integer

【消费门槛】消费门槛,单位:分。
特殊规则:取值范围 1 ≤ value ≤ 10000000


 discount_coupon  选填   object

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

属性

 discount_percent  选填   integer

【折扣比例】折扣百分比,88为88折


 transaction_minimum  选填   integer

【消费门槛】消费门槛,单位:分。
特殊规则:取值范围 1 ≤ value ≤ 10000000


 exchange_coupon  选填   object

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

属性

 exchange_price  选填   integer

【单品换购价】单品换购价,单位:分。
特殊规则:取值范围 0 ≤ value ≤ 10000000


 transaction_minimum  选填   integer

【消费门槛】消费门槛,单位:分。
特殊规则:取值范围 1 ≤ value ≤ 10000000


 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

【发放规则】发放规则

属性

 max_amount  选填   integer

【批次总预算】总预算金额,单位分
注:该字段暂未开放


 max_coupons  选填   integer

【批次最大发放个数】批次最大可发放个数限制
特殊规则:取值范围 1 ≤ value ≤ 1000000000


 max_coupons_per_user  必填   integer

【用户最大可领个数】用户可领个数,每个用户最多100张券。


 max_amount_by_day  选填   integer

【单天发放上限金额】单天发放上限金额
注:该字段暂未开放


 max_coupons_by_day  选填   integer

【单天发放上限个数】单天发放上限个数(stock_type为DISCOUNT或EXCHANGE时可传入此字段控制单天发放上限)。
特殊规则:取值范围 1 ≤ value ≤ 1000000000


 natural_person_limit  选填   boolean

【是否开启自然人限领】不填默认否,枚举值:
true:是
false:否
注:自然人防刷即同证件号下的所有账户合并计算的限领次数(限领次数指的是参数字段“用户最大领取个数”填写的值)


 prevent_api_abuse  选填   boolean

【可疑账号拦截】true-是;false-否,不填默认否


 transferable  选填   boolean

【是否允许转赠,暂不开放】不填默认否,枚举值:
true:是
false:否
该字段暂未开放


 shareable  选填   boolean

【是否允许分享链接,暂不开放】不填默认否,枚举值:
true:是
false:否
该字段暂未开放


 custom_entrance  选填   object

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

属性

 mini_programs_info  选填   object

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

属性

 mini_programs_appid  必填   string

【商家小程序AppID】商家小程序AppID要与归属商户号有M-A or M-m-suba关系。
校验规则:传入的AppID得是与调用方商户号(即请求头里面的商户号)有绑定关系的AppID 或 传入的AppID得是归属商户号有绑定关系的AppID


 mini_programs_path  必填   string

【商家小程序path】商家小程序path


 entrance_words  必填   string(5)

【入口文案】入口文案,字数上限为5个,一个中文汉字/英文字母/数字均占用一个字数。


 guiding_words  选填   string(6)

【引导文案】小程序入口引导文案,用户自定义字段。字数上限为6个,一个中文汉字/英文字母/数字均占用一个字数。


 appid  选填   string

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


 hall_id  选填   string

【更多优惠入口;营销馆创建地址:https://pay.weixin.qq.com/index.php/xphp/cfav_market/hall#/pages/list/lis填写微信支付营销馆的馆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

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

属性

 finder_id  选填   string

【视频号ID】关联视频号将展示在优惠券详情的顶部右侧,作为跳转去视频号的入口,入参参数请配置视频号id,请前往视频号助手管理查看视频号ID


 finder_video_id  选填   string

【视频号视频ID】券详情视频内容,支持配置关联视频号下的具体视频内容,入参参数请配置视频id,请前往视频号助手管理后台复制具体视频ID


 finder_video_cover_image_url  选填   string

【视频号封面图】截取的视频号图片将在券到期提醒消息、券详情中展示。
1.图片尺寸:716像素(宽)*402像素(高);图片大小不超过2M,支持JPG/PNG格式。
2.仅支持通过《图片上传API》接口获取的图片URL地址。


 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的数量信息

属性

 total_count  必填   integer

【该批次总共已上传的code总数】该批次总共已上传的code总数


 available_count  必填   integer

【该批次当前可用的code数】该批次当前可用的code数


 notify_config  选填   object

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

属性

 notify_appid  选填   string(64)

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


 send_count_information  选填   object

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

属性

 total_send_num  选填   integer

【已发放券张数】批次已发放的券数量,满减、折扣、换购类型会返回该字段


 total_send_amount  选填   integer

【已发放券金额】批次已发放的预算金额,满减券类型会返回该字段


 today_send_num  选填   integer

【单天已发放券张数】批次当天已发放的券数量,设置了单天发放上限的满减、折扣、换购类型返回该字段


 today_send_amount  选填   integer

【单天已发放券金额】批次当天已发放的预算金额,设置了当天发放上限的满减券类型返回该字段


 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

NO_AUTH

无权限

查看具体错误信息,确认是否有权限

403

RULE_LIMIT

券不在有效期内

请确认券是否能在当前时间核销

404

RESOURCE_NOT_EXISTS

查询的资源不存在

请检查查询资源的对应ID是否填写正确

404

USER_NOT_EXISTS

OpenID不正确

请确认传入的OpenID是否正确

429

FREQUENCY_LIMITED

频率限制

调用太频繁,请降低调用接口频率

500

SYSTEM_ERROR

系统失败

多为网络超时引起,重试

 

 

元宝AI
反馈
目录
置顶