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

查询用户单张券详情API

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


服务商可通过该接口查询微信用户卡包中某一张商家券的详情信息。

接口说明

适用对象: 服务商

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

请求方式:GET


path 指该参数为路径参数

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

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


请求参数

参数名 变量 类型[长度限制] 必填 描述
券code coupon_code string[1,32] path 券的唯一标识。
示例值:123446565767
公众账号ID appid string[1,32] path 支持传入与当前调用接口商户号有绑定关系的appid。支持小程序appid与公众号appid。
校验规则:传入的APPID得是与调用方商户号(即请求头里面的商户号)有绑定关系的APPID或传入的APPID得是归属商户号有绑定关系的APPID
示例值:wx233544546545989
用户标识 openid string[1,128] path Openid信息,用户在appid下的唯一标识。
校验规则:传入的openid得是调用方商户号(即请求头里面的商户号)有绑定关系的APPID获取的openid或传入的openid得是归属商户号有绑定关系的APPID获取的openid。获取openid文档
示例值:2323dfsdf342342

请求示例


https://api.mch.weixin.qq.com/v3/marketing/busifavor/users/2323dfsdf342342/coupons/123446565767/appids/wx233544546545989
    
{
JAVA示例代码
}
    

返回参数

参数名 变量 类型[长度限制] 必填 描述
批次归属商户号 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:已过期
DEACTIVATED:已失效
示例值:SENDED

+样式信息 display_pattern_info object 商家券详细信息
参数名 变量 类型[长度限制] 必填 描述
使用须知 description string[1,1000] 用于说明详细的活动规则,会展示在代金券详情页。
示例值:深圳南山门店可用
商户logo merchant_logo_url string[1,128] 若券归属商户号有认证品牌,则系统将自动拉取对应品牌logo;若券归属商户号不在认证品牌下,需自定义上传logo,未上传时将展示兜底灰色logo样式,影响券详情页用户体验,请及时上传。
商户logo的URL地址,可通过《图片上传API》获得图片URL地址。
示例值:https://qpic.cn/xxx
商户名称 merchant_name string[1,16] 不支持商户自定义。若券归属商户号有认证品牌,系统将自动拉取认证品牌号下的品牌名称;若券归属商户号不在认证品牌下,则拉取本商户号的商户简称。展示上限12个字符。
示例值:微信支付
背景颜色 background_color string[1,15] 代金券的背景颜色,可设置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秒。
2、若券批次设置为领取后可用,则开始时间即为券的领取时间;若券批次设置为领取后第X天可用,则开始时间为券领取时间后第X天00:00:00可用。
示例值:2019-12-30T13: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
关联的商户订单号 associate_out_trade_no string[1,128] 若商家券操作过关联商户订单信息,则该字段返回商家券已关联的商户订单号。
示例值: mchtrade_1234554
券核销时间 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

卡券背景颜色图

返回示例



{
  "belong_merchant": "100000222",
  "stock_name": "商家券",
  "comment": "xxx可用",
  "goods_name": "xxx商品可用",
  "stock_type": "NORMAL",
  "transferable": false,
  "shareable": false,
  "coupon_state": "SENDED",
  "display_pattern_info": {
    "description": "xxx门店可用",
    "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"
}
                                

    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已达上限 请更换一个新的批次后重试


技术咨询

文档反馈