---
url: "https://pay.weixin.qq.com/doc/v3/partner/4012492796.md"
title: "查询代金券详情"
doc_id: 4012492796
---

>更新时间：2024.11.18

通过此接口可查询代金券信息，包括代金券的基础信息、状态。

注意：该接口支持批次创建商户号与批次发放商户调用

接口频率：不区分来源 1000/s， 单ip 500/s

接口耗时：1S

幂等规则：接口支持幂等重入




## 接口说明

支持商户：【普通服务商】　【从业机构（银行）】　【从业机构（支付机构）】　【渠道商】　【清算机构】

请求方式：【GET】 `/v3/marketing/favor/users/{openid}/coupons/{coupon_id}`

请求域名：【主域名】https://api.mch.weixin.qq.com 使用该域名将访问就近的接入点

　　　　　【备域名】https://api2.mch.weixin.qq.com 使用该域名将访问异地的接入点，指引[点击查看](https://pay.weixin.qq.com/doc/v3/partner/4012082567.md)

## 请求参数

### Header 参数
| 参数名 | 类型 | 必填 | 描述 |
| --- |  --- | --- | --- |
| Authorization | string | true | 请参考[签名认证](https://pay.weixin.qq.com/doc/v3/partner/4012365870.md#%E8%AF%B7%E6%B1%82%E6%8E%A5%E5%8F%A3%E5%90%8E%E7%AB%AF%E7%AD%BE%E5%90%8D)生成认证信息 |
| Accept | string | true | 请设置为 `application/json` |
### Path 参数
| 参数名 | 类型 | 必填 | 描述 |
| --- |  --- | --- | --- |
| coupon_id | string(20) | true | 【代金券或消费金id】微信为代金券或消费金唯一分配的id。[发放代金券API返回的数据](https://pay.weixin.qq.com/doc/v3/partner/4012463807.md) |
| openid | string(128) | true | 【用户openid】openid是微信用户在appid下的唯一用户标识（appid不同，则获取到的openid就不同），可用于永久标记一个用户。<br>[获取openid的方式](https://pay.weixin.qq.com/doc/v3/partner/4012081935.md#OpenID) |
### Query 参数
| 参数名 | 类型 | 必填 | 描述 |
| --- |  --- | --- | --- |
| appid | string(128) | true | 【公众账号ID 】微信为调用商户分配的公众账号ID，接口传入的appid应该为公众号的appid和小程序的appid（在[微信公众平台](https://mp.weixin.qq.com/)申请）或APP的appid（在[微信开发平台](https://open.weixin.qq.com/)申请）。<br>校验规则：<br>1、该appid需要与接口传入中的openid有对应关系；<br>2、该appid需要与调用接口的商户号（即请求头中的商户号）有绑定关系，若未绑定，可参考该指引完成绑定 （[商家商户号与AppID账号关联管理](https://kf.qq.com/faq/1801116VJfua1801113QVNVz.html)） |
## 应答参数

200 OK

| 参数名 | 类型 | 必填 | 描述 |
| --- |  --- | --- | --- |
| stock_creator_mchid | string | true | 【创建批次的商户号】 微信为创建方商户分配的商户号 |
| stock_id | string | true | 【批次号】 微信为每个代金券批次分配的唯一id。 |
| coupon_id | string | true | 【代金券或消费金id】 微信为代金券或消费金唯一分配的id |
| cut_to_message | object | false | 【单品优惠特定信息】 单品优惠特定信息 |
| cut_to_message.single_price_max | integer | true | 【可用优惠的商品最高单价】 可用优惠的商品最高单价，单位：分。 |
| cut_to_message.cut_to_price | integer | true | 【减至后的优惠单价】 减至后的优惠单价，单位：分。 |
| coupon_name | string | true | 【券或消费金名称】 券或消费金名称 |
| status | string | true | 【券或消费金状态】 券或消费金状态：<br>SENDED：可用<br>USED：已实扣<br>EXPIRED：已过期<br>RECOVER：已回收<br>REVOKED: 已失效 |
| description | string | true | 【使用说明】 券或消费金描述说明字段 |
| create_time | string | true | 【领券时间】 领券时间，遵循 [rfc3339](https://datatracker.ietf.org/doc/html/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秒。 |
| coupon_type | string | true | 【券或消费金类型】 券或消费金类型：<br>NORMAL：满减券<br>CUT\_TO：减至券 |
| no_cash | boolean | true | 【是否无资金流】 枚举值：<br>true：是<br>false：否 |
| available_begin_time | string | true | 【可用开始时间】 可用开始时间，遵循 [rfc3339](https://datatracker.ietf.org/doc/html/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秒。 |
| available_end_time | string | true | 【可用结束时间】 可用结束时间，遵循 [rfc3339](https://datatracker.ietf.org/doc/html/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秒。 |
| singleitem | boolean | true | 【是否单品优惠】 枚举值：<br>true：是<br>false：否 |
| normal_coupon_information | object | false | 【满减券或消费金信息】 普通满减券或消费金面额、门槛信息。 |
| normal_coupon_information.coupon_amount | integer | true | 【面额】 面额，单位：分。 |
| normal_coupon_information.transaction_minimum | integer | true | 【门槛】 使用券金额门槛，单位：分。 |
| out_request_no | string | false | 【商户单据号】 商户此次发放凭据号 |
| available_balance | integer | false | 【剩余金额】 可用余额，单位：分。<br>仅有当business\_type=MULTIUSE时，才会返回。 |
| business_type | string | false | 【业务类型】 细分业务类型，仅当business\_type=MULTIUSE时才返回，枚举值：<br>MULTIUSE：消费金<br>可选取值<br><ul><li>`MULTIUSE`:  消费金类型</li></ul> |
| discount_msg | object | false | 【折扣券信息】 折扣券金面额、门槛信息。 |
| discount_msg.discount_amount_max | integer | true | 【最高折扣金额】 最高折扣金额，单位分 |
| discount_msg.discount_percent | integer | true | 【折扣百分比】 折扣百分比，例如88-八八折 |
| discount_msg.transaction_minimum | integer | false | 【门槛】 使用券金额门槛，单位分 |
## 错误码

### 公共错误码

| 状态码 | 错误码 | 描述 | 解决方案 |
| --- | --- | --- | --- |
| 400 | PARAM\_ERROR | 参数错误 | 请根据错误提示正确传入参数 |
| 400 | INVALID\_REQUEST | HTTP 请求不符合微信支付 APIv3 接口规则 | 请参阅 [接口规则](https://pay.weixin.qq.com/doc/v3/partner/4012081726.md) |
| 401 | SIGN\_ERROR | 验证不通过 | 请参阅 [签名常见问题](https://pay.weixin.qq.com/doc/v3/partner/4012082324.md) |
| 500 | SYSTEM\_ERROR | 系统异常，请稍后重试 | 请稍后重试 |

### 业务错误码

| 状态码 | 错误码 | 描述 | 解决方案 |
| --- | --- | --- | --- |
| 400 | APPID\_MCHID\_NOT\_MATCH | 商户号与AppID不匹配 | 请绑定调用接口的商户号和AppID后重试 |
| 400 | INVALID\_REQUEST | OpenID与AppID不匹配 | 请使用AppID下的OpenID |
| 400 | INVALID\_REQUEST | 活动已结束或未激活 | 请检查批次状态 |
| 400 | INVALID\_REQUEST | 非法的商户号 | 请检查商户号是否正确 |
| 400 | MCH\_NOT\_EXISTS | 商户号不合法 | 请输入正确的商户号 |
| 400 | PARAM\_ERROR | 回调URL不能为空 | 请填写回调URL |
| 400 | PARAM\_ERROR | 回调商户不能为空 | 请填写回调商户 |
| 400 | PARAM\_ERROR | 券ID必填 | 请填写券ID |
| 400 | PARAM\_ERROR | AppID必填 | 请输入AppID |
| 400 | PARAM\_ERROR | OpenID必填 | 请输入OpenID |
| 400 | PARAM\_ERROR | 页大小超过阈值 | 请不要超过最大的页大小 |
| 400 | PARAM\_ERROR | 输入时间格式错误 | 请输入正确的时间格式 |
| 400 | PARAM\_ERROR | 批次号必填 | 请输入批次号 |
| 400 | PARAM\_ERROR | 商户号必填 | 请输入商户号 |
| 400 | PARAM\_ERROR | 非法的批次状态 | 请检查批次状态 |
| 403 | NOT\_ENOUGH | 批次预算不足 | 请补充预算 |
| 403 | REQUEST\_BLOCKED | 调用商户无权限 | 请开通产品权限后再调用该接口 |
| 403 | REQUEST\_BLOCKED | 商户无权发券 | 调用接口的商户号无权发券，请检查是否是自己的批次或是已授权的批次。 |
| 403 | REQUEST\_BLOCKED | 批次不支持跨商户发券 | 该批次未做跨商户号的授权，请授权后再发放 |
| 403 | REQUEST\_BLOCKED | 用户被限领拦截 | 用户领取已经达到上限，请调高上限或停止发放。 |
| 403 | USER\_ACCOUNT\_ABNORMAL | 用户非法 | 该用户账号异常，无法领券。商家可联系微信支付或让用户联系微信支付客服处理。 |
| 404 | RESOURCE\_NOT\_EXISTS | 批次不存在 | 请检查批次ID是否正确 |
| 429 | FREQUENCY\_LIMIT\_EXCEED | 接口限频 | 请降低调用频率 |
| 429 | FREQUENCY\_LIMITED | 请求过于频繁 | 稍后重试 |

请求示例

- [curl 示例](https://pay.weixin.qq.com/doc/v3/partner/4012492796-curl.md)
- [Java 示例](https://pay.weixin.qq.com/doc/v3/partner/4012492796-java.md)
- [Go 示例](https://pay.weixin.qq.com/doc/v3/partner/4012492796-go.md)


应答示例

> 200 OK

```
{
  "stock_creator_mchid" : "9800064",
  "stock_id" : "9865888",
  "coupon_id" : "98674556",
  "cut_to_message" : {
    "single_price_max" : 100,
    "cut_to_price" : 80
  },
  "coupon_name" : "微信支付代金券",
  "status" : "EXPIRED",
  "description" : "微信支付营销",
  "create_time" : "2015-05-20T13:29:35.120+08:00",
  "coupon_type" : "CUT_TO",
  "no_cash" : false,
  "available_begin_time" : "2015-05-20T13:29:35.120+08:00",
  "available_end_time" : "2015-05-20T13:29:35.120+08:00",
  "singleitem" : false,
  "normal_coupon_information" : {
    "coupon_amount" : 100,
    "transaction_minimum" : 100
  },
  "out_request_no" : "example_out_request_no",
  "available_balance" : 10000,
  "business_type" : "MULTIUSE",
  "discount_msg" : {
    "discount_amount_max" : 100,
    "discount_percent" : 88,
    "transaction_minimum" : 100
  }
}

```
