代金券、现金券查询接口
更新时间：2025-08-03
代金券、现金券查询GetCouponList接口
接口描述
分页获取客户名下的代金券、现金券详情。企业组织财务管理中的主账户可以查询子账户的代金券、现金券详情。子用户要发起该请求，需要具有多用户访问控制的 FCFullControlPolicy 权限或者 FCReadAccessPolicy 权限。 默认接口请求频率限制：20次/秒。
权限说明
请求发起人需要具有合法的AccessKeyID和SecretAccessKey才能发起请求，请参考 鉴权认证。
注意事项
如果请求中没有用户验证信息（即匿名访问），返回403 Forbidden，错误信息：AccessDenied。
请求结构
Plain Text
1POST /v{version}/coupons/list HTTP/1.1
2Host: billing.baidubce.com
3ContentType: application/json
4Authorization: authorization string请求头域
除公共头域外，无其它特殊头域。
请求参数
| 名称 | 类型 | 参数位置 | 描述 | 是否必须 |
|---|---|---|---|---|
| startTime | String | Query参数 | 代金券发放开始时间，格式：yyyy-MM-ddTHH:mm:ssZ，例：2025-08-03T16:00:00Z | 可选 |
| endTime | String | Query参数 | 代金券发放结束时间，格式：yyyy-MM-ddTHH:mm:ssZ，例：2025-08-0316:00:00Z。 若传值后，需要与 startTime 一起传，返回结果当时有效状态的代金券（有效包含UNUSED，USING，USED_UP） |
可选 |
| couponStatus | String | Query参数 | 代金券的状态： 未生效：INACTIVE 未使用：UNUSED 使用中：USING 已用完：USED_UP 已过期：EXPIRED 已作废： INVALID |
可选 |
| couponTypes | List |
Query参数 | 券类型： 代金券：CASH_COUPON 现金券：CASH_EQUIVALENT_COUPON 折扣券：DISCOUNT_COUPON 例如 ["CASH_COUPON", "DISCOUNT_COUPON"] |
可选 |
| queryAccountId | String | Query参数 | 查询账户ID，只有企业组织（或者虚商）的主账户可以查询加入财务圈（或者虚商组织）的子账户账单，否则会提示AccessDenied | 可选 |
| pageNo | int | Query参数 | 分页查询的页数，默认为1 | 可选 |
| pageSize | int | Query参数 | 每页包含的最大数量，最大数量通常不超过100，缺省值为20。 | 可选 |
响应头域
除公共头域外，无其它特殊头域。
响应参数
| 名称 | 类型 | 描述 |
|---|---|---|
| startTime | String | 此处为查询条件中的startTime |
| endTime | String | 此处为查询条件中的endTime |
| accountId | String | 当前账户不是财务圈子账户时，返回当前账户accountId；是财务圈子账户时，返回当前账户主账户的accountId |
| loginName | String | 当前账户不是财务圈子账户时，返回当前账户的登录名；是财务圈子账户时，返回当前账户主账户的登录名 |
| subAccountId | String | 当前账户不是财务圈子账户时，返回”/”；是财务圈子账户时，返回当前账户的accountId |
| subLoginName | String | 当前账户不是财务圈子账户时，返回”/”；是财务圈子账户时，返回当前账户的登录名 |
| ouName | String | 当前账户不是财务圈子账户时，返回”/”；是财务圈子账户时，返回当前账户所在组织单元的单元名 |
| pageNo | Integer | 分页查询的页数 |
| pageSize | Integer | 每页包含的最大数量 |
| totalCount | Integer | 当前查询条件总条目 |
| couponList | List |
代金券/现金券信息列表 |
请求示例
说明：一次请求最多返回1000个代金券的信息。
Plain Text
1GET / HTTP/1.1
2Host: billing.baidubce.com
3Date: Wed, 06 Apr 2016 06:34:40 GMT
4Authorization: AuthorizationString
5{
6 "couponTypes" : [ "CASH_COUPONS", "DISCOUNT_COUPON" ],
7 "pageNo": 1,
8 "pageSize": 20
9}响应示例
Plain Text
1HTTP/1.1 200 OK
2x-bce-request-id: d4591fcf-025b-46bc-81eb-91ddda4e27bc
3Server: BWS
4Date: Tue, 09 Apr 2019 11:01:10 GMT
5Content-Type: application/json;charset=UTF-8
6{
7 "accountId": "accountId",
8 "loginName": "loginName",
9 "pageNo": 1,
10 "pageSize": 20,
11 "totalCount": 3,
12 "couponList": [
13 {
14 "couponName": "DE9TDWQHGGSD4MN",
15 "status": "UNUSED",
16 "createTime": "2025-08-03T06:13:42Z",
17 "beginTime": "2025-08-03T16:00:00Z",
18 "endTime": "2025-08-03T15:59:59Z",
19 "discountRate": 50,
20 "couponType": "DISCOUNT_COUPON",
21 "productName": "云服务器 BCC",
22 "region": "华北-北京",
23 "orderType": "通用",
24 "scenarios": "单产品单订单消费需满10元 (最大抵扣金额：100.00元)",
25 "remark": "代金券备注信息"
26 },
27 {
28 "couponName": "DXSSA5I2IQ8U585",
29 "status": "UNUSED",
30 "createTime": "2025-08-03T06:09:28Z",
31 "beginTime": "2025-08-03T16:00:00Z",
32 "endTime": "2025-08-03T15:59:59Z",
33 "totalAmount": 1.0000,
34 "balance": 1.0000,
35 "couponType": "CASH_COUPON",
36 "productName": "云服务器 BCC",
37 "region": "全局产品",
38 "orderType": "新购",
39 "scenarios": "预付费单订单通用",
40 "remark": "代金券备注信息"
41 },
42 {
43 "couponName": "DD3YJSK66LNHE12",
44 "status": "INVALID",
45 "createTime": "2025-08-03T09:34:40Z",
46 "beginTime": "2025-08-03T16:00:00Z",
47 "endTime": "2025-08-03T15:59:59Z",
48 "totalAmount": 12.0000,
49 "balance": 12.0000,
50 "couponType": "CASH_COUPON",
51 "productName": "应用引擎 BAEPRO,云虚拟主机 BCH,云监控 BCM,Elasticsearch,MapReduce BMR,内容发布网络 CDN,简单消息服务 SMS",
52 "region": "全局产品",
53 "orderType": "通用",
54 "scenarios": "预付费单订单通用",
55 "remark": ""
56 }
57 ]
58}
59
60
61## 数据类型
62### Model对象定义
63### CouponInfo
64| 名称 | 类型 |描述 |
65| --- | --- | --- |
66|couponName|String|代金券号，如：D1SYU2KEFYPKXEN
67|status|String|代金券状态，取值：<br> INVALID 未生效<br> UNUSED 未使用<br>USING 使用中<br> USED_UP 已用完<br>CANCELLED 已作废<br>EXPIRED 已过期<br>
68|createTime|String|代金券创建时间（发放时间），如 2025-08-03T15:15:50Z
69|beginTime|String|代金券开始时间（生效时间），如 2025-08-03T15:15:50Z
70|endTime|String|代金券过期时间，如 2025-08-03T15:15:50Z
71|totalAmount|BigDecimal|总额
72|balance|BigDecimal|余额
73|discountRate|int|折扣率，如：80，表示 80%，仅折扣券才返回此字段
74|couponType|String|券类型：<br>代金券：CASH_COUPON<br>现金券：CASH_EQUIVALENT_COUPON<br>折扣券：DISCOUNT_COUPON<br>
75|productName|String|适用产品描述，如：弹性伸缩 ,应用引擎 BAEPRO,弹性裸金属服务器 BBC,云服务器 BCC,容器实例 BCI。<br>注意，该字段的分割符是英文逗号：","。
76|region|String|区域（中文）
77|orderType|String|适用订单类型，如：购买,续费,升配。<br>注意，该字段的分割符是英文逗号：","。<br>全量的订单类型枚举如下：<br>NEW(新购)、RENEW(续费)、SHIFT_CHARGE(后付费计费方案变更)、DILATATION(升级)、SHRINKAGE(降级)、RESIZE(后付费变配)、COMPENSATE_TIME(赔付时长)、REFUND(退款)、TRANSFER_IN(转入)、TO_PREPAY(后付费转预付费)、TO_POSTPAY(预付费转后付费)、TIME_EXPAND(续时订单)。<br>注意：返回值为括号内的中文。
78|scenarios|String|适用场景描述，如：通用/单产品单订单消费需满400元(follow控制台适用场景，控制台应该是有拼接规则的)
79|remark|String|代金券备注