查询代金券详情API

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


通过此接口可查询代金券信息,包括代金券的基础信息、状态。如代金券已核销,会包括代金券核销的订单信息(订单号、单品信息等)。

接口说明

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

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

请求方式:GET

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


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

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


请求参数

参数名 变量 类型 必填 描述
代金券id coupon_id string(20) path 微信为每个代金券批次分配的唯一id。
示例值:9856888
公众账号ID appid string(128) path 微信为发券方商户分配的公众账号ID,接口传入的所有appid应该为公众号的appid(在mp.weixin.qq.com申请的),不能为APP的appid(在open.weixin.qq.com申请的)。
示例值:wx233544546545989
用户openid openid string(128) path openid信息,用户在appid下的唯一标识。
示例值:2323dfsdf342342

请求示例


https://api.mch.weixin.qq.com/v3/marketing/favor/users/2323dfsdf342342/coupons/985688?appid=wx233544546545989
    
{
JAVA示例代码
}
    

返回参数

参数名 变量 类型 必填 描述
创建批次的商户号 stock_creator_mchid string(20) 批次创建方商户号
示例值:9800064
批次号 stock_id string(20) 微信为每个代金券批次分配的唯一id。
示例值:9865888
代金券id coupon_id string(20) 微信为代金券唯一分配的id。
示例值:98674556
+ 单品优惠特定信息 cut_to_message

object

单品优惠特定信息。
参数名 变量 类型 必填 描述
可用优惠的商品最高单价 single_price_max uint64 可用优惠的商品最高单价,单位:分。
示例值:100
减至后的优惠单价 cut_to_price uint64 减至后的优惠单价,单位:分。
示例值:100
代金券名称 coupon_name string(20) 代金券名称
示例值:微信支付代金券
代金券状态 status string
代金券状态:
SENDED:可用
USED:已实扣
EXPIRED:已过期
示例值:EXPIRED
使用说明 description string(3000) 代金券描述说明字段。
示例值:微信支付营销
领券时间 create_time string(32) 领券时间,遵循rfc3339标准格式,格式为YYYY-MM-DDTHH:mm:ss:sss+TIMEZONE,YYYY-MM-DD表示年月日,T出现在字符串中,表示time元素的开头,HH:mm:ss:sss表示时分秒毫秒,TIMEZONE表示时区(+08:00表示东八区时间,领先UTC 8小时,即北京时间)。例如:2015-05-20T13:29:35.120+08:00表示,北京时间2015年5月20日 13点29分35秒。
示例值: 2015-05-20T13:29:35.120+08:00
券类型 coupon_type string
券类型:
NORMAL:满减券
CUT_TO:减至券
示例值:CUT_TO
是否无资金流 no_cash bool 枚举值:
true:是
false:否
示例值:true
可用开始时间 available_begin_time string(32) 可用开始时间,遵循rfc3339标准格式,格式为YYYY-MM-DDTHH:mm:ss:sss+TIMEZONE,YYYY-MM-DD表示年月日,T出现在字符串中,表示time元素的开头,HH:mm:ss:sss表示时分秒毫秒,TIMEZONE表示时区(+08:00表示东八区时间,领先UTC 8小时,即北京时间)。例如:2015-05-20T13:29:35.120+08:00表示,北京时间2015年5月20日 13点29分35秒。
示例值: 2015-05-20T13:29:35.120+08:00
可用结束时间 available_end_time string(32) 可用结束时间,遵循rfc3339标准格式,格式为YYYY-MM-DDTHH:mm:ss:sss+TIMEZONE,YYYY-MM-DD表示年月日,T出现在字符串中,表示time元素的开头,HH:mm:ss:sss表示时分秒毫秒,TIMEZONE表示时区(+08:00表示东八区时间,领先UTC 8小时,即北京时间)。例如:2015-05-20T13:29:35.120+08:00表示,北京时间2015年5月20日 13点29分35秒。
示例值: 2015-05-20T13:29:35.120+08:00
是否单品优惠 singleitem bool 枚举值:
true:是
false:否
示例值:true
+ 满减券信息 normal_coupon_information

object

普通满减券面额、门槛信息。
参数名 变量 类型 必填 描述
面额 coupon_amount uint64 面额,单位:分。
示例值:100
门槛 transaction_minimum uint64 使用券金额门槛,单位:分。
示例值:100
+已实扣代金券核销信息 consume_information

object

已实扣代金券信息。
参数名 变量 类型 必填 描述
核销时间 consume_time string(32) 核销时间,遵循rfc3339标准格式,格式为YYYY-MM-DDTHH:mm:ss:sss+TIMEZONE,YYYY-MM-DD表示年月日,T出现在字符串中,表示time元素的开头,HH:mm:ss:sss表示时分秒毫秒,TIMEZONE表示时区(+08:00表示东八区时间,领先UTC 8小时,即北京时间)。例如:2015-05-20T13:29:35.120+08:00表示,北京时间2015年5月20日 13点29分35秒。
示例值: 2015-05-20T13:29:35.120+08:00
核销商户号 consume_mchid string(20) 核销商户号
示例值: 9856081
支付单号 transaction_id string(32) 核销订单号
示例值: 2345234523
+ 单品信息 goods_detail array 商户下单单品信息
参数名 变量 类型 必填 描述
商品编码 goods_id string(128) 单品id
示例值: a_goods1
商品数量 quantity uint32 单品数量
示例值: 7
商品价格 price uint64 单品价格
示例值: 1
优惠金额 discount_amount uint64 优惠金额
示例值: 4

返回示例


{
  "stock_creator_mchid": "9800064",
  "stock_id": "9865888",
  "coupon_id": "98674556",
  "cut_to_message": {
    "single_price_max": 100,
    "cut_to_price":100
  },
  "coupon_name": "微信支付代金券",
  "status": "EXPIRED",
  "description": "微信支付营销",
  "create_time": "2015-05-20T13:29:35.120+08:00",
  "coupon_type": "CUT_TO",
  "no_cash": null,
  "available_begin_time": "2015-05-20T13:29:35.120+08:00",
  "available_end_time": "2015-05-20T13:29:35.120+08:00",
  "singleitem": null,
  "normal_coupon_information": {
    "coupon_amount": 100,
    "transaction_minimum": 100
  },
  "consume_information": {
    "consume_time": "2015-05-20T13:29:35.120+08:00",
    "consume_mchid": "9856081",
    "transaction_id": "2345234523",
    "goods_detail": [
      {
        "goods_id": "a_goods1",
        "quantity": 7,
        "price": 1,
        "discount_amount": 4
      }
    ]
  }
}
                                

    http://2323weixin.qq.com
                                

错误码公共错误码

状态码 错误码 描述 解决方案
400 PARAM_ERROR 回调url不能为空 请填写回调url
PARAM_ERROR 回调商户不能为空 请填写回调商户
PARAM_ERROR 券id必填 请填写券id
PARAM_ERROR appid必填 请输入appid
PARAM_ERROR openid必填 请输入openid
PARAM_ERROR 页大小超过阈值 请不要超过最大的页大小
PARAM_ERROR 输入时间格式错误 请输入正确的时间格式
PARAM_ERROR 批次号必填 请输入批次号
PARAM_ERROR 商户号必填 请输入商户号
PARAM_ERROR 非法的批次状态 请检查批次状态
400 MCH_NOT_EXISTS 商户号不合法 请输入正确的商户号
400 INVALID_REQUEST openid与appID不匹配 请使用appID下的的openid
INVALID_REQUEST 活动已结束或未激活 请检查批次状态
INVALID_REQUEST 非法的商户号 请检查商户号是否正确
400 APPID_MCHID_NOT_MATCH 商户号与appid不匹配 请绑定调用接口的商户号和APPID后重试
403 USER_ACCOUNT_ABNORMAL 用户非法 该用户账号异常,无法领券。商家可联系微信支付或让用户联系微信支付客服处理。
403 NOT_ENOUGH 批次预算不足 请补充预算
403 REQUEST_BLOCKED 调用商户无权限 请开通产品权限后再调用该接口
REQUEST_BLOCKED 商户无权发券 调用接口的商户号无权发券,请检查是否是自己的批次或是已授权的批次。
REQUEST_BLOCKED 批次不支持跨商户发券 该批次未做跨商户号的授权,请授权后再发放
REQUEST_BLOCKED 用户被限领拦截 用户领取已经达到上限,请调高上限或停止发放。
404 RESOURCE_NOT_EXISTS 批次不存在 请检查批次ID是否正确
429 FREQUENCY_LIMIT_EXCEED 接口限频 请降低调用频率

版本说明

关闭
V1.0
2019年09月27日
1. 查询批次详情接口上线