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

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


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

接口说明

适用对象:直连商户 服务商 渠道商

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

请求方式:GET

接口规则:https://wechatpay-api.gitbook.io/wechatpay-api-v3


path 指该参数为路径参数

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

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


请求参数

参数名 变量 类型[长度限制] 必填 描述
用户标识 openid string[1,128] path Openid信息,用户在appid下的唯一标识。
示例值:2323dfsdf342342
公众账号ID appid string[1,32] query 支持传入与当前调用接口商户号有绑定关系的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
+券核销规则 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秒。
示例值: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秒。
示例值: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 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 折扣百分比,例如:88为八八折
示例值:88
消费门槛 transaction_minimum int64 消费门槛,单位分
特殊规则:取值范围 1 ≤ value ≤ 10000000
示例值:100
+换购券使用规则 exchange_coupon object stock_type为EXCHANGE时必填。
参数名 变量 类型[长度限制] 必填 描述
单品换购价 exchange_price int64 单品换购价,单位:分。
特殊规则:取值范围 1 ≤ value ≤ 10000000
示例值:100
消费门槛 transaction_minimum int64 消费门槛,单位:分。
特殊规则:取值范围 1 ≤ 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,32] 发券时传入的唯一凭证
示例值: 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

返回示例


> 200 Response
{
  "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": "xxxxx",
        "coupon_image_url": "图片cdn地址"
      },
      "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
        },
        "discount_coupon": {
          "discount_percent": 88,
          "transaction_minimum": 100
        },
        "exchange_coupon": {
          "exchange_price": 100,
          "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已达上限 请更换一个新的批次后重试

版本说明

关闭
V1.3
2020年07月24日
1.新增code展示模式字段code_display_mode
V1.2
2020年03月20日
1.stock_name的字段长度改为24、merchant_name字段长度改为16、核销方式枚举值:“USER_SELF”改为“SELF_CONSUME”;
2.新增send_request_no、use_request_no、use_time 3字段。
V1.1
2020年01月08日
1. 核销方式(use_method)新增枚举值PAYMENT_CODE、修改批次类型枚举值
2. 返回参数新增券可使用开始时间(available_start_time)、券过期时间(expire_time)、券领取时间(receive_time)字段

技术咨询

反馈有奖