查询优惠券列表
功能介绍
伙伴可以查询自身的优惠券信息。
伙伴登录伙伴中心查询已发放代金券列表请参见这里,查看已下发代金券的内容。
- 目前国际站没有现金券和折扣券。
- 不返回超过已失效一年时间的代金券/折扣券信息。
- 当券的失效时间小于当前时间时,券将不再有效,此时券的状态称之为已失效。
接口约束
该接口使用合作伙伴的AK/SK或者Token调用时,只能查询合作伙伴或伙伴名下云经销商的优惠券列表信息。若是查询伙伴名下客户的优惠券,需要置换子客户token,置换前需伙伴申请客户授权或客户给伙伴创建委托。
调试
您可以在API Explorer中调试该接口,支持自动认证鉴权。API Explorer可以自动生成SDK代码示例,并提供SDK代码示例调试功能。
URI
GET /v2/promotions/benefits/coupons
参数说明请参见下表。
参数 |
是否必选 |
参数类型 |
取值范围 |
描述 |
---|---|---|---|---|
coupon_id |
否 |
String |
最大长度:64 |
优惠券ID。 此参数不携带或携带值为空时,不作为筛选条件。 |
order_id |
否 |
String |
最大长度:64 |
订单ID。 此参数不携带或携带值为空时,不作为筛选条件。 |
promotion_plan_id |
否 |
String |
最大长度:64 |
促销计划ID。 此参数不携带或携带值为空时,不作为筛选条件。 |
coupon_type |
否 |
Integer |
[1-4] |
优惠券类型:
此参数不携带或携带值为空或携带值为null时,不作为筛选条件;不支持携带值为空串。 |
status |
否 |
Integer |
[1-5] |
客户优惠券实例状态:
此参数不携带或携带值为空时,不作为筛选条件。 |
active_start_time |
否 |
String |
最大长度:64 |
激活开始时间。 UTC时间,格式:yyyy-MM-dd'T'HH:mm:ss'Z',如“2019-05-06T08:05:01Z”。其中,HH范围是0~23,mm和ss范围是0~59。 此参数不携带或携带值为空时,不作为筛选条件;不支持携带值为空串或携带值为null。 |
active_end_time |
否 |
String |
最大长度:64 |
激活结束时间。 UTC时间,格式:yyyy-MM-dd'T'HH:mm:ss'Z',如“2019-05-06T08:05:01Z”。其中,HH范围是0~23,mm和ss范围是0~59。 此参数不携带或携带值为空时,不作为筛选条件;不支持携带值为空串或携带值为null。 |
offset |
否 |
Integer |
[0-最大整数] |
偏移量,从0开始。默认值为0。
说明:
offset用于分页处理,如不涉及分页,请使用默认值0。offset表示相对于满足条件的第一个数据的偏移量。如offset = 1,则返回满足条件的第二个数据至最后一个数据。 示例1,满足查询条件的结果共10条数据,limit取值为10,offset取值为1,则返回的数据为2~10,第一条数据不返回。 示例2,查询总数20条,期望每页返回10条数据,则获取第一页数据,入参offset填写0,limit填写10;获取第二页数据,入参offset填写10,limit填写10。 |
limit |
否 |
Integer |
[1-100] |
查询的优惠券数量,默认值为10。 |
source_id |
否 |
String |
最大长度:255 |
发券来源,如果是合作伙伴发送的券,此处为伙伴ID。 如果需要查询某个伙伴发放的券,可以在此处输入该伙伴ID。 此参数不携带或携带值为空或携带值为null时,不作为筛选条件;携带值为空串时,作为筛选条件。 |
请求消息
请求参数
无。
请求示例
GET https://bss-intl.myhuaweicloud.com/v2/promotions/benefits/coupons HTTP/1.1 Content-Type: application/json X-Auth-Token:MIIPAgYJKoZIhvcNAQcCo...ggg1BBIINPXsidG9rZ
响应消息
响应参数
参数 |
参数类型 |
取值范围 |
描述 |
---|---|---|---|
error_code |
String |
最大长度:16 |
状态码。 具体请参见状态码。 |
error_msg |
String |
最大长度:1024 |
错误描述信息。 |
count |
Integer |
- |
符合查询条件的总条数。 |
user_coupons |
List<IQueryUserCouponsResult> |
- |
优惠券记录。 具体请参见表2。 |
参数 |
参数类型 |
描述 |
---|---|---|
coupon_id |
String |
优惠券实例ID。 |
coupon_code |
String |
优惠券编码。 |
status |
Integer |
优惠券状态:
|
customer_id |
String |
客户账号ID。 |
coupon_type |
Integer |
优惠券类型:
|
measure_id |
Integer |
度量单位。 1:元 |
face_value |
Double |
优惠券金额。 |
valid_time |
String |
生效时间。 UTC时间,格式:yyyy-MM-dd'T'HH:mm:ss'Z',如“2019-05-06T08:05:01Z”。 |
expire_time |
String |
失效时间。 UTC时间,格式:yyyy-MM-dd'T'HH:mm:ss'Z',如“2019-05-06T08:05:01Z”。 |
order_id |
String |
订单ID。
说明:
优惠券被多次交易抵扣场景下,返回每次抵扣订单号用英文分号分割,同一次交易抵扣场景下,如果是合并支付,会存在多个订单号,用英文逗号分割。举例:CS1904011928GIBHC1,CS1904011928GIBHC2,CS1904011928GIBHC3;CS1904011928GIBHCB。 存在多个订单号时,不表示全部订单号都使用了该优惠券。 |
promotion_plan_id |
String |
促销计划ID。 |
plan_name |
String |
促销计划名称。 |
plan_desc |
String |
促销计划描述。 |
media_type |
Integer |
介质类型。
|
fetch_method |
Integer |
获取方式:
|
use_limits |
List<ICouponUseLimitInfoV2> |
优惠券使用限制。 具体请参见表3。 |
active_time |
String |
激活时间。 UTC时间,格式:yyyy-MM-dd'T'HH:mm:ss'Z',如“2019-05-06T08:05:01Z”。 |
reserve_time |
String |
使用时间。 UTC时间,格式:yyyy-MM-dd'T'HH:mm:ss'Z',如“2019-05-06T08:05:01Z”。 |
promotion_id |
String |
促销ID。 |
create_time |
String |
创建时间。 UTC时间,格式:yyyy-MM-dd'T'HH:mm:ss'Z',如“2019-05-06T08:05:01Z”。 |
coupon_version |
Integer |
优惠券版本:
|
balance |
Double |
优惠券余额。单位:元。 |
lock_order_id |
String |
锁定优惠券的订单ID。 |
coupon_usage |
String |
优惠券用途。 |
is_frozen |
String |
优惠券是否冻结:
|
currency |
String |
币种。 USD:美元 |
extend_param1 |
String |
扩展字段。 |
source_id |
String |
发券来源。
|
参数 |
参数类型 |
描述 |
---|---|---|
use_limiti_info_id |
String |
使用限制ID,主键。 |
limit_key |
String |
折扣限制,key的取值请参考表4。 |
value1 |
String |
value1。 |
value2 |
String |
value2。 |
value_unit |
String |
value单位。 |
limit_type |
String |
限制类型。 |
promotion_plan_id |
String |
促销计划ID。 |
key值 |
含义 |
说明 |
备注 |
---|---|---|---|
baseValue |
订单金额 |
value1中保存订单金额下限,value2中保存订单金额上限。 |
支持代金券,现金券,折扣券 |
serviceType |
云服务类型 |
只有value1有效,具体的云服务类型请调用查询云服务类型列表接口获取。 |
支持代金券,现金券,折扣券 |
regionCode |
区域编码 |
value2中保存区域名称,value1中保存区域编码。 |
支持代金券,现金券,折扣券 |
productId |
产品ID |
可以包含多个产品ID,英文逗号分隔。 |
支持代金券,现金券,折扣券 |
subscribeType |
订购类型 |
只有value1有效。取值为:
|
支持代金券,现金券,折扣券 |
firstOrderInService |
首次购买限制 |
只有value1有效。 |
支持代金券,现金券,折扣券 |
cycleNum |
周期数量 |
只有value1有效。 |
支持代金券,现金券,折扣券 |
cycleType |
适用周期类型 |
|
支持代金券,现金券,折扣券,折扣券仅支持包年/包月 |
simultaneousUseWithEmpowerDiscount |
代金券是否可以和授权折扣同享 |
代金券是否可以和授权折扣(包括商务折扣和伙伴授予折扣)同享。
|
支持代金券,现金券,折扣券,折扣券只能使用0。 |
usageTimes |
是否支持多次使用 |
是否支持多次使用,值保存在value1中。取值为:
|
|
isOnlyForStrictSelected |
是否只能用于云商店严选产品 |
是否只能用于云商店严选产品,值保存在value1中。取值为:
如果没有这个限制,等同于0;该限制只是用于现金券。 |
支持现金券 |
isRebate |
是否参与伙伴激励返点 |
是否参与伙伴激励返点,值保存在value1中。取值为:
该限制只是用于现金券。 |
支持现金券 |
serviceTypeBlackList |
服务类型黑名单 |
服务类型黑名单,value1中保存服务类型编码;该限制只是用于现金券。 |
支持现金券 |
minConsumeDiscount |
最低客户消费折扣 |
最低客户消费折扣,值保存在value1中。取值为0-1之间(不包括0和1)。 |
支持代金券、现金券 |
isForAnnualContracts |
是否只能用于包年/包月1年的订单 |
是否只能用于包年/包月1年的订单。取值为:
|
支持代金券、折扣券 |
simultaneousUseWithPromotionProduct |
是否可以和促销产品同享 |
代金券是否可以和促销产品同享,值保存在value1中。取值为:
|
支持代金券/折扣券 |
simultaneousUseWithPromotionDiscount |
是否可以和促销折扣同享 |
代金券是否可以和促销折扣同享,值保存在value1中。取值为:
|
支持代金券 |
simultaneousUseWithDiscountCoupon |
是否可以和折扣券同享 |
代金券是否可以和折扣券同享,值保存在value1中。取值为:
|
支持代金券 |
响应示例
HTTP/1.1 200 OK Content-Type: application/json;charset=UTF-8 Content-Length: length Date: response time { "count": "1", "user_coupons": [ { "coupon_id": "CP19092406014086E3", "coupon_code": "CP19092406014086E3", "status": "2", "customer_id": "c9e731c4663646988ef4cdb3122837b6", "coupon_type": "1", "measure_id": "1", "face_value": "100", "valid_time": "2019-09-16T16:00:00Z", "expire_time": "2019-09-16T16:00:00Z", "order_id": "CS1904011928GIBHC", "promotion_plan_id": "promotionPlanId5322584", "plan_name": "532美元优惠券name", "plan_desc": "532美元优惠券desc", "media_type": "1", "fetch_method": "1", "use_limits": [ { "use_limiti_info_id": "CP19092406014086E3", "limit_key": "simultaneousUseWithDiscountCoupon", "value1": "1", "value2": "", "value_unit": "", "limit_type": "=", "promotion_plan_id": "promotionPlanId5322584" } ], "active_time": "2019-09-16T16:00:00Z", "reserve_time": "2019-09-16T16:00:00Z", "promotion_id": "promotionPlanId5322584", "create_time": "2019-09-16T16:00:00Z", "coupon_version": "2", "balance": "100", "lock_order_id": "CS1904011928GIBHC", "coupon_usage": "170719190603338056FEH60VIRWEP", "is_frozen": "0", "currency": "USD", "extend_param1": "2019091702368200", "source_id": "c9e731c4663646988ef4cdb3122837b6" } ] }