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

更新时间：2024.10.31

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

接口说明

支持商户：【普通商户】

请求方式：【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: 已失效

请求示例

1curl -X GET \
2  https://api.mch.weixin.qq.com/v3/marketing/busifavor/users/2323dfsdf342342/coupons?appid=wx233544546545989&stock_id=100088&creator_merchant=1000000001&belong_merchant=1000000002&sender_merchant=1000000003&offset=0&limit=20&coupon_state=SENDED \
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

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

属性

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

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: 二维码

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	系统失败	多为网络超时引起，重试

文档是否有帮助

更多支持

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