根据过滤条件查询用户的券

更新时间:2025.07.25

商户自定义筛选条件(如创建商户号、归属商户号、发放商户号等),查询指定微信用户卡包中满足对应条件的所有商家券信息。

接口说明

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

请求方式:【GET】/v3/marketing/busifavor/users/{openid}/coupons

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

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

请求参数

Header  HTTP头参数

 Authorization  必填 string

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


 Accept  必填 string

请设置为application/json


path  路径参数

 openid  必填   string

【用户标识】Openid信息,用户在AppID下的唯一标识。
校验规则:传入的OpenID得是调用方商户号(即请求头里面的商户号)有绑定关系的AppID获取的OpenID或传入的OpenID得是归属商户号有绑定关系的AppID获取的OpenID。获取OpenID文档


query  查询参数

 appid  必填   string

【公众账号ID】支持传入与当前调用接口商户号有绑定关系的AppID。支持小程序AppID与公众号AppID。
校验规则:传入的AppID得是与调用方商户号(即请求头里面的商户号)有绑定关系的AppID 或 传入的AppID得是归属商户号有绑定关系的AppID


 stock_id  选填   string

【批次号】批次号,是否指定批次号查询


 creator_merchant  选填   string

【创建批次的商户号】批次创建方商户号
校验规则:当调用方商户号(即请求头中的商户号)为创建批次方商户号时,该参数必传


 belong_merchant  选填   string

【批次归属商户号】批次归属商户号
校验规则:当调用方商户号(即请求头中的商户号)为批次归属商户号时,该参数必传


 sender_merchant  选填   string

【批次发放商户号】批次发放商户号
校验规则:当调用方商户号(即请求头中的商户号)为批次发放商户号时,该参数必传;委托营销关系下,请填写委托发券的商户号


 offset  选填   integer

【分页页码】分页页码


 limit  选填   integer

【分页大小】分页大小


 coupon_state  选填   string

【券状态】商家券状态

可选取值:

  • SENDED: 可用

  • USED: 已核销

  • EXPIRED: 已过期

  • DELETED: 已删除

  • DEACTIVATED: 已失效

请求示例

curl
Java
Go

GET

1curl -X GET \
2  https://api.mch.weixin.qq.com/v3/marketing/busifavor/users/2323dfsdf342342/coupons?appid=wx233544546545989&stock_id=100088&coupon_state=SENDED&creator_merchant=1000000001&belong_merchant=1000000002&sender_merchant=1000000003&offset=0&limit=20 \
3  -H "Authorization: WECHATPAY2-SHA256-RSA2048 mchid=\"1900000001\",..." \
4  -H "Accept: application/json" 
5

应答参数
折叠全部参数

200 OK

 data  选填   array[object]

【结果集】

属性

 belong_merchant  必填   string

【批次归属商户号】代金券的所属商户号


 stock_name  必填   string

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


 comment  选填   string

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


 goods_name  必填   string

【适用商品范围】适用商品范围,字数上限为15个,一个中文汉字/英文字母/数字均占用一个字数。


 stock_type  必填   string

【批次类型】批次类型

可选取值:

  • NORMAL: 固定面额满减券批次

  • DISCOUNT: 折扣券批次

  • EXCHANGE: 换购券批次


 transferable  选填   boolean

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


 shareable  选填   boolean

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


 coupon_state  选填   string

【券状态】商家券状态

可选取值:

  • SENDED: 可用

  • USED: 已核销

  • EXPIRED: 已过期

  • DELETED: 已删除

  • DEACTIVATED: 已失效


 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地址。


 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】核销方式为线上小程序核销才有效


 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/list】 填写微信支付营销馆的馆ID,用户自定义字段。营销馆需在商户平台创建。


 store_id  选填   string

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


 code_display_mode  选填   string

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

可选取值:

  • NOT_SHOW: 不展示code

  • BARCODE: 一维码

  • QRCODE: 二维码


 coupon_code  选填   string

【券code】券的唯一标识


 stock_id  选填   string

【批次号】批次号


 available_start_time  选填   string

【券可使用开始时间】用户领取到的这张券实际可使用的开始时间:如批次设置的领取后可用,则开始时间即为券的领取时间; 如批次设置的领取后第X天可用,则为领取时间后第X天00:00:00


 expire_time  选填   string

【券过期时间】用户领取到这张券的过期时间


 receive_time  选填   string

【券领取时间】用户领取到这张券的时间


 send_request_no  选填   string

【发券请求单号】发券时传入的唯一凭证


 use_request_no  选填   string

【核销请求单号】核销时传入的唯一凭证(如券已被核销,将返回此字段)


 use_time  选填   string

【券核销时间】券被核销的时间(如券已被核销,将返回此字段)


 associate_out_trade_no  选填   string

【关联的商户订单号】若商家券操作过关联商户订单信息,则该字段返回商家券已关联的商户订单号。


 return_request_no  选填   string

【回退请求单号】回退时传入的唯一凭证(如券发生了退回,将返回此字段)


 return_time  选填   string

【券回退时间】券被回退的时间(如券发生了退回,将返回此字段)


 deactivate_request_no  选填   string

【失效请求单号】失效时传入的唯一凭证(如果一张券已失效,将返回此字段)


 deactivate_time  选填   string

【券失效时间】券被失效的时间(如果一张券已失效,将返回此字段)


 deactivate_reason  选填   string

【失效原因】失效一张券的原因(如果一张券已失效,可能返回此字段)


 total_count  必填   integer

【总数量】总数量


 limit  必填   integer

【分页大小】分页大小


 offset  必填   integer

【分页页码】分页页码

应答示例

200 OK

1{
2  "data" : [
3    {
4      "belong_merchant" : "100000222",
5      "stock_name" : "商家券",
6      "comment" : "xxx可用",
7      "goods_name" : "xxx商品可用",
8      "stock_type" : "NORMAL",
9      "transferable" : false,
10      "shareable" : false,
11      "coupon_state" : "SENDED",
12      "display_pattern_info" : {
13        "description" : "xxx门店可用",
14        "merchant_logo_url" : "https://xxx",
15        "merchant_name" : "微信支付",
16        "background_color" : "xxxxx",
17        "coupon_image_url" : "图片cdn地址",
18        "finder_info" : {
19          "finder_id" : "sph6Rngt2T4RlUf",
20          "finder_video_id" : "export/UzFfAgtgekIEAQAAAAAAb4MgnPInmAAAAAstQy6ubaLX4KHWvLEZgBPEwIEgVnk9HIP-zNPgMJofG6tpdGPJNg_ojtEjoT94",
21          "finder_video_cover_image_url" : "https://wxpaylogo.qpic.cn/xxx"
22        }
23      },
24      "coupon_use_rule" : {
25        "coupon_available_time" : {
26          "available_begin_time" : "2015-05-20T13:29:35+08:00",
27          "available_end_time" : "2015-05-20T13:29:35+08:00",
28          "available_day_after_receive" : 3,
29          "available_week" : {
30            "week_day" : [
31              1
32            ],
33            "available_day_time" : [
34              {
35                "begin_time" : 3600,
36                "end_time" : 86399
37              }
38            ]
39          },
40          "irregulary_avaliable_time" : [
41            {
42              "begin_time" : "2015-05-20T13:29:35+08:00",
43              "end_time" : "2015-05-20T13:29:35+08:00"
44            }
45          ],
46          "wait_days_after_receive" : 7
47        },
48        "fixed_normal_coupon" : {
49          "discount_amount" : 5,
50          "transaction_minimum" : 100
51        },
52        "discount_coupon" : {
53          "discount_percent" : 88,
54          "transaction_minimum" : 100
55        },
56        "exchange_coupon" : {
57          "exchange_price" : 100,
58          "transaction_minimum" : 100
59        },
60        "use_method" : "OFF_LINE",
61        "mini_programs_appid" : "wx23232232323",
62        "mini_programs_path" : "/path/index/index"
63      },
64      "custom_entrance" : {
65        "mini_programs_info" : {
66          "mini_programs_appid" : "wx234545656765876",
67          "mini_programs_path" : "/path/index/index",
68          "entrance_words" : "欢迎选购",
69          "guiding_words" : "获取更多优惠"
70        },
71        "appid" : "wx324345hgfhfghfg",
72        "hall_id" : "233455656",
73        "store_id" : "233554655",
74        "code_display_mode" : "NOT_SHOW"
75      },
76      "coupon_code" : "123446565767",
77      "stock_id" : "1002323",
78      "available_start_time" : "2019-12-30T13:29:35+08:00",
79      "expire_time" : "2019-12-31T13:29:35+08:00",
80      "receive_time" : "2019-12-30T13:29:35+08:00",
81      "send_request_no" : "MCHSEND202003101234",
82      "use_request_no" : "MCHUSE202003101234",
83      "use_time" : "2019-12-31T13:29:35+08:00",
84      "associate_out_trade_no" : "2000-01-01T00:00:00+08:00",
85      "return_request_no" : "MCHRETURN202003101234",
86      "return_time" : "2020-07-31T13:29:35+08:00",
87      "deactivate_request_no" : "MCHRETURN202003101234",
88      "deactivate_time" : "2020-07-31T13:29:35+08:00",
89      "deactivate_reason" : "此券使用时间错误"
90    }
91  ],
92  "total_count" : 100,
93  "limit" : 10,
94  "offset" : 1
95}
96

 

错误码

公共错误码

状态码

错误码

描述

解决方案

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
反馈
目录
置顶