商户进件
特约商户进件
基础支付
JSAPI支付
APP支付
H5支付
Native支付
小程序支付
合单支付
付款码支付
经营能力
支付即服务
点金计划
行业方案
平台收付通(商户进件)
平台收付通(普通支付)
平台收付通(合单支付)
平台收付通(分账)
平台收付通(补差)
平台收付通(退款)
平台收付通(余额查询)
平台收付通(商户提现)
平台收付通(注销申请)
平台收付通(注销后提现)
平台收付通(跨境付款)
平台收付通(下载账单)
智慧商圈
微信支付分停车服务
电子发票
营销工具
代金券
商家券
委托营销
支付有礼
小程序发券插件
H5发券
图片上传(营销专用)
现金红包
资金应用
分账
连锁品牌分账
风险合规
商户开户意愿确认
消费者投诉2.0
商户违规通知回调
其他能力
图片上传
视频上传
微信支付平台证书

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

最新更新时间:2023.11.23 版本说明


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

接口说明

适用对象: 服务商

请求URL:https://api.mch.weixin.qq.com/v3/marketing/busifavor/users/{openid}/coupons

请求方式:GET


path 指该参数为路径参数

query 指该参数需在请求URL传参

body 指该参数需在请求JSON传参


请求参数

参数名 变量 类型[长度限制] 必填 描述
用户标识 openid string[1,128] path Openid信息,用户在appid下的唯一标识。
校验规则:传入的openid得是调用方商户号(即请求头里面的商户号)有绑定关系的APPID获取的openid或传入的openid得是归属商户号有绑定关系的APPID获取的openid。获取openid文档
示例值:2323dfsdf342342
公众账号ID appid string[1,32] query 支持传入与当前调用接口商户号有绑定关系的appid。支持小程序appid与公众号appid。
校验规则:传入的APPID得是与调用方商户号(即请求头里面的商户号)有绑定关系的APPID 或 传入的APPID得是归属商户号有绑定关系的APPID
示例值:wx233544546545989
批次号 stock_id string[1,20] query 微信为每个商家券批次分配的唯一ID,是否指定批次号查询。
示例值:9865000
券状态 coupon_state string[1,16]

query 券状态

枚举值:
SENDED:可用
USED:已核销
EXPIRED:已过期
示例值:SENDED

创建批次的商户号 creator_merchant string[1,32] query 批次创建方商户号
校验规则:当调用方商户号(即请求头中的商户号)为创建批次方商户号时,该参数必传
示例值:1000000001
批次归属商户号 belong_merchant string[8,15] query 批次归属商户号
校验规则:当调用方商户号(即请求头中的商户号)为批次归属商户号时,该参数必传
示例值:1000000002
批次发放商户号 sender_merchant string[1,32] query 批次发放商户号
校验规则:当调用方商户号(即请求头中的商户号)为批次发放商户号时,该参数必传;委托营销关系下,请填写委托发券的商户号
示例值:1000000003
分页页码 offset int query 分页页码
示例值:0
分页大小 limit int query 分页大小
示例值:20

请求示例


https://api.mch.weixin.qq.com/v3/marketing/busifavor/users/2323dfsdf342342/coupons?appid=wx233544546545989&stock_id=9865000&coupon_state=USED&creator_merchant=1000000001&offset=0&limit=20

    
{
JAVA示例代码
}
    

返回参数

说明:为提升API性能,返回参数中“结果集>样式信息>使用须知(description)”字段内容将不再返回,即查询结果不再返回使用须知,改动将于2020年7月8日12:00生效。如您业务中需要使用该字段,建议使用“查询用户单张券详情API

参数名 变量 类型[长度限制] 必填 描述
+结果集 data array 结果集
参数名 变量 类型[长度限制] 必填 描述
批次归属商户号 belong_merchant string[8,15] 批次归属于哪个商户。
示例值:10000022
商家券批次名称 stock_name string[1,21] 批次名称,字数上限为21个,一个中文汉字/英文字母/数字均占用一个字数。
示例值:商家券
批次备注 comment string[1,20] 仅配置商户可见,用于自定义信息。字数上限为20个,一个中文汉字/英文字母/数字均占用一个字数。
示例值:xxx可用
适用商品范围 goods_name string[1,15] 适用商品范围,字数上限为15个,一个中文汉字/英文字母/数字均占用一个字数。
示例值:xxx商品可用
批次类型 stock_type string[1,128] 批次类型
NORMAL:固定面额满减券批次
DISCOUNT:折扣券批次
EXCHANGE:换购券批次
示例值:NORMAL
是否允许转赠 transferable bool 不填默认否,枚举值:
true:是
false:否
该字段暂未开放
示例值:false
是否允许分享领券链接 shareable bool 不填默认否,枚举值:
true:是
false:否
该字段暂未开放
示例值:false
券状态 coupon_state string[1,16] 商家券状态
枚举值:
SENDED:可用
USED:已核销
EXPIRED:已过期
示例值:SENDED
+样式信息 display_pattern_info object 商家券详细信息
参数名 变量 类型[长度限制] 必填 描述
商户logo merchant_logo_url string[1,128] 商户logo的URL地址,可通过《图片上传API》获得图片URL地址。
示例值:https://qpic.cn/xxx
商户名称 merchant_name string[1,16] 商户名称,字数上限为16个,一个中文汉字/英文字母/数字均占用一个字数。
示例值:微信支付
背景颜色 background_color string[1,16] 代金券的背景颜色,可设置10种颜色,色值请参考卡券背景颜色图。颜色取值为颜色图中的颜色名称。
示例值:Color020
券详情图片 coupon_image_url string[1,128] 券详情图片,850像素*350像素,且图片大小不超过2M,支持JPG/PNG格式,可通过《图片上传API》获得图片URL地址。
示例值:https://qpic.cn/xxx
+ 视频号相关信息 finder_info object 视频号相关信息
参数名 变量 类型[长度限制] 必填 描述
视频号ID finder_id string[1,32] 关联视频号将展示在优惠券详情的顶部右侧,作为跳转去视频号的入口,请求参数请配置视频号ID,请前往视频号助手管理查看视频号ID
示例值:sph6Rngt2T4RlUf
视频号视频ID finder_video_id string[1,256] 券详情视频内容,支持配置关联视频号下的具体视频内容,请求参数请配置视频ID,请前往视频号助手管理后台复制具体视频ID
示例值:export/UzFfAgtgekIEAQAAAAAAb4MgnPInmAAAAAstQy6ubaLX4KHWvLEZgBPEwIEgVnk9HIP-zNPgMJofG6tpdGPJNg_ojtEjoT94
视频号封面图 finder_video_cover_image_url string[1,256] 截取的视频号图片将在券到期提醒消息、券详情中展示。
1.图片尺寸:716像素(宽)*402像素(高);图片大小不超过2M,支持JPG/PNG格式。
2.仅支持通过《图片上传API》接口获取的图片URL地址。
示例值:https://wxpaylogo.qpic.cn/xxx
+券核销规则 coupon_use_rule 券核销规则 券核销相关规则
参数名 变量 类型[长度限制] 必填 描述
+券可核销时间 coupon_available_time object 日期区间内可以使用优惠。
参数名 变量 类型[长度限制] 必填 描述
开始时间 available_begin_time string[1,32] 批次开始时间,遵循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年。
示例值:2015-05-20T13:29:35+08:00
结束时间 available_end_time string[1,32] 批次结束时间,遵循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年。
示例值:2015-05-20T13:29:35+08:00
生效后N天内有效 available_day_after_receive int 日期区间内,券生效后x天内有效。例如生效当天内有效填1,生效后2天内有效填2,以此类推。注意,用户在有效期开始前领取商家券,则从有效期第1天开始计算天数,用户在有效期内领取商家券,则从领取当天开始计算天数,无论用户何时领取商家券,商家券在活动有效期结束后均不可用。可配合wait_days_after_receive一同填写,也可单独填写。单独填写时,有效期内领券后立即生效,生效后x天内有效。
示例值:3
+ 固定周期有效时间段 available_week object 可以设置多个星期下的多个可用时间段,比如每周二10点到18点,用户自定义字段。
参数名 变量 类型[长度限制] 必填 描述
可用星期数 week_day array[int] 0代表周日,1代表周一,以此类推。
示例值:1, 2
+ 当天可用时间段 available_day_time array 可以填写多个时间段,最多不超过2个。
参数名 变量 类型[长度限制] 必填 描述
当天可用开始时间 begin_time int 当天可用开始时间,单位:秒,1代表当天0点0分1秒。
示例值:3600
当天可用结束时间 end_time int 当天可用结束时间,单位:秒,86399代表当天23点59分59秒。
示例值:86399
+ 无规律的有效时间段 irregulary_avaliable_time array 无规律的有效时间,多个无规律时间段,用户自定义字段。
参数名 变量 类型[长度限制] 必填 描述
开始时间 begin_time string[1,32] 开始时间,遵循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秒。
示例值:2015-05-20T13:29:35+08:00
结束时间 end_time string[1,32] 结束时间,遵循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秒。
示例值:2015-05-20T13:29:35+08:00
领取后N天开始生效 wait_days_after_receive int 日期区间内,用户领券后需等待x天开始生效。例如领券后当天开始生效则无需填写,领券后第2天开始生效填1,以此类推。用户在有效期开始前领取商家券,则从有效期第1天开始计算天数,用户在有效期内领取商家券,则从领取当天开始计算天数。无论用户何时领取商家券,商家券在活动有效期结束后均不可用。需配合available_day_after_receive一同填写,不可单独填写。
示例值:7
+固定面额满减券使用规则 fixed_normal_coupon object 三选一 stock_type为NORMAL时必填。
参数名 变量 类型[长度限制] 必填 描述
优惠金额 discount_amount int64 优惠金额,单位:分。
特殊规则:取值范围 1 ≤ value ≤ 10000000
示例值:5
消费门槛 transaction_minimum int64 消费门槛,单位:分。
特殊规则:取值范围 1 ≤ value ≤ 10000000
示例值:100
+折扣券使用规则 discount_coupon object stock_type为DISCOUNT时必填
参数名 变量 类型[长度限制] 必填 描述
折扣比例 discount_percent int 折扣百分比,例如:86为八六折
示例值:86
消费门槛 transaction_minimum int64 消费门槛,单位分
特殊规则:取值范围 1 ≤ value ≤ 10000000
示例值:100
+换购券使用规则 exchange_coupon object stock_type为EXCHANGE时必填。
参数名 变量 类型[长度限制] 必填 描述
单品换购价 exchange_price int64 单品换购价,单位:分。
特殊规则:取值范围 0 ≤ value ≤ 10000000
示例值:100
消费门槛 transaction_minimum int64 消费门槛,单位:分。
特殊规则:取值范围 0 ≤ value ≤ 10000000
示例值:100
核销方式 use_method string[1,128] 枚举值:
OFF_LINE:线下滴码核销,点击券“立即使用”跳转展示券二维码详情。
MINI_PROGRAMS:线上小程序核销,点击券“立即使用”跳转至配置的商家小程序(需要添加小程序appid和path)。
PAYMENT_CODE:微信支付付款码核销,点击券“立即使用”跳转至微信支付钱包付款码。
SELF_CONSUME:用户自助核销,点击券“立即使用”跳转至用户自助操作核销界面(当前暂不支持用户自助核销)。
示例值:OFF_LINE
小程序appid mini_programs_appid string[1,32] 条件选填 核销方式为线上小程序核销才有效。
示例值:wx23232232323
小程序path mini_programs_path string[1,128] 条件选填 核销方式为线上小程序核销才有效。
示例值:/path/index/index
+自定义入口 custom_entrance object 卡详情页面,可选择多种入口引导用户。
参数名 变量 类型[长度限制] 必填 描述
+小程序入口 mini_programs_info object

需要小程序APPID、path、入口文案、引导文案。如果需要跳转小程序,APPID、path、入口文案为必填,引导文案非必填。

appid要与归属商户号有M-A or M-m-suba关系。

参数名 变量 类型[长度限制] 必填 描述
商家小程序appid mini_programs_appid string[1,32] 商家小程序appid要与归属商户号有M-A or M-m-suba关系。
示例值:wx234545656765876
商家小程序path mini_programs_path string[1,128] 商家小程序path
示例值:/path/index/index
入口文案 entrance_words string[1,5] 入口文案,字数上限为5个,一个中文汉字/英文字母/数字均占用一个字数。
示例值:欢迎选购
引导文案 guiding_words string[1,6] 小程序入口引导文案,用户自定义字段。字数上限为6个,一个中文汉字/英文字母/数字均占用一个字数。
示例值:获取更多优惠
商户公众号appid appid string[1,32] 可配置商户公众号,从券详情可跳转至公众号,用户自定义字段。
示例值:wx324345hgfhfghfg
营销馆id hall_id string[1,64] 填写微信支付营销馆的馆id,用户自定义字段。 营销馆需在服务商平台 创建。
示例值:233455656
可用门店id store_id string[1,64] 填写代金券可用门店id,用户自定义字段。
示例值:233554655
code展示模式 code_display_mode string[1,8] 枚举值:
NOT_SHOW:不展示code
BARCODE:一维码
QRCODE:二维码
示例值:BARCODE
券code coupon_code string[1,32] 券的唯一标识。
示例值:123446565767
批次号 stock_id string[1,20] 微信为每个商家券批次分配的唯一ID,是否指定批次号查询。
示例值:1002323
券可使用开始时间 available_start_time string[1,32] 1、用户领取到该张券实际可使用的开始时间,遵循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秒。
示例值:2015-05-20T13:29:35+08:00
券过期时间 expire_time string[1,32] 用户领取到该张券的过期时间,遵循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秒。
示例值:2015-05-20T13:29:35+08:00
券领券时间 receive_time string[1,32] 用户领取到该张券的时间,遵循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秒。
示例值:2015-05-20T13:29:35+08:00
发券请求单号 send_request_no string[1,128] 发券时传入的唯一凭证
示例值: MCHSEND202003101234
核销请求单号 use_request_no string[1,32] 核销时传入的唯一凭证(如券已被核销,将返回此字段)
示例值: MCHUSE202003101234
券核销时间 use_time string[1,32] 券被核销的时间(如券已被核销,将返回此字段);遵循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秒。
示例值:2015-05-20T13:29:35+08:00
总数量 total_count int 总数量
示例值: 100
分页页码 offset int 分页页码
示例值:1
分页大小 limit int 分页大小
示例值:10

卡券背景颜色图

返回示例



{
  "data": [
    {
      "belong_merchant": "100000222",
      "stock_name": "商家券",
      "comment": "xxx可用",
      "goods_name": "xxx商品可用",
      "stock_type": "NORMAL",
      "transferable": false,
      "shareable": "false",
      "coupon_state": "SENDED",
      "display_pattern_info": {
        "merchant_logo_url": "https://xxx",
        "merchant_name": "微信支付",
        "background_color": "Color020",
        "coupon_image_url": "https://qpic.cn/xxx",
        "finder_info": {
          "finder_id": "sph6Rngt2T4RlUf",
          "finder_video_cover_image_url": "https://wxpaylogo.qpic.cn/xxx",
          "finder_video_id": "export/UzFfAgtgekIEAQAAAAAAb4MgnPInmAAAAAstQy6ubaLX4KHWvLEZgBPEwIEgVnk9HIP-zNPgMJofG6tpdGPJNg_ojtEjoT94"
        }
      },
      "coupon_use_rule": {
        "coupon_available_time": {
          "available_begin_time": "2015-05-20T13:29:35+08:00",
          "available_end_time": "2015-05-20T13:29:35+08:00",
          "available_day_after_receive": 3,
          "available_week": {
            "week_day": [
              "1",
              "2"
            ],
            "available_day_time": [
              {
                "begin_time": 3600,
                "end_time": 86399
              }
            ]
          },
          "irregulary_avaliable_time": [
            {
              "begin_time": "2015-05-20T13:29:35+08:00",
              "end_time": "2015-05-20T13:29:35+08:00"
            }
          ]
        },
        "fixed_normal_coupon": {
          "discount_amount": 5,
          "transaction_minimum": 100
        },
        "use_method": "OFF_LINE",
        "mini_programs_appid": "wx23232232323",
        "mini_programs_path": "/path/index/index"
      },
      "custom_entrance": {
        "mini_programs_info": {
          "mini_programs_appid": "wx234545656765876",
          "mini_programs_path": "/path/index/index",
          "entrance_words": "欢迎选购",
          "guiding_words": "获取更多优惠"
        },
        "appid": "wx324345hgfhfghfg",
        "hall_id": "233455656",
        "store_id": "233554655"
      },
      "coupon_code": "123446565767",
      "stock_id": "1002323",
      "available_start_time": "2019-12-30T13:29:35+08:00",
      "expire_time": "2019-12-31T13:29:35+08:00",
      "receive_time": "2019-12-30T13:29:35+08:00",
	  "send_request_no": "MCHSEND202003101234",
	  "use_request_no": "MCHSEND202003101234",
	  "use_time": "2019-12-30T13:29:35+08:00"
    }
  ],
  "total_count": 100,
  "limit": 10,
  "offset": 1
}
                                

    http://2323weixin.qq.com
                                

错误码公共错误码

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


技术咨询

文档反馈