文档首页/ 合作伙伴中心/ API参考/ 管理交易/ 管理优惠券/ 查询已发放的优惠券

更新时间：2024-10-24 GMT+08:00

查看PDF

查询已发放的优惠券

功能介绍

合作伙伴可以查询已发放的优惠券列表。

伙伴登录伙伴中心，进入“客户业务 > 代金/现金券管理”，选择“已发放代金/现金券”页签，即可查询已发放的代金/现金券。

不返回已失效超两年时间（含当天）的代金券/折扣券信息。
当券的失效时间小于当前时间时，券将不再有效，此时券的状态称之为已失效。
在API只可以查询代售子客户已发放的代金/现金劵，在伙伴中心可以查询代售和顾问销售已发放的代金/现金劵，对比一致性时需要注意关联模式是否一致。

接口约束

该接口只能给合作伙伴使用，调用的时候必须传递合作伙伴的AK/SK或者Token。

调试

您可以在API Explorer中调试该接口。

URI

GET /v2/promotions/benefits/partner-coupons

参数说明请参见下表。

表1 查询参数
参数	是否必选	参数类型	取值范围	描述
coupon_id	否	String	最大长度：64	优惠券ID。此参数不携带或携带值为空时，不作为筛选条件；携带值为null时，作为筛选条件；不支持携带值为空串。
customer_id	否	String	最大长度：64	客户账号ID。您可以调用查询客户列表接口获取customer_id。此参数不携带或携带值为空时，不作为筛选条件；携带值为null时，作为筛选条件；不支持携带值为空串。
order_id	否	String	最大长度：64	订单ID。此参数不携带或携带值为空时，不作为筛选条件；携带值为null时，作为筛选条件；不支持携带值为空串。
coupon_type	否	Integer	-	优惠券类型。 1：代金券 4：现金券此参数不携带或携带值为空或携带值为null时，不作为筛选条件。
status	否	Integer	-	客户优惠券实例状态： 2：可使用 3：已使用 4：已过期 5：已回收此参数不携带或携带值为空或携带值为null时，不作为筛选条件。
create_time_begin	否	String	最大长度：20	创建时间（开始）。 UTC时间，格式：yyyy-MM-dd'T'HH:mm:ss'Z'，如“2019-05-06T08:05:01Z”。其中，HH范围是0～23，mm和ss范围是0～59。输入这个条件，会查询出创建时间大于这个时间的记录。此参数不携带或携带值为空时，不作为筛选条件。
create_time_end	否	String	最大长度：20	创建时间（结束）。 UTC时间，格式：yyyy-MM-dd'T'HH:mm:ss'Z'，如“2019-05-06T08:05:01Z”。其中，HH范围是0～23，mm和ss范围是0～59。输入这个条件，会查询出创建时间小于这个时间的记录。此参数不携带或携带值为空时，不作为筛选条件。
effective_time_begin	否	String	最大长度：20	生效时间（开始）。 UTC时间，格式：yyyy-MM-dd'T'HH:mm:ss'Z'，如“2019-05-06T08:05:01Z”。其中，HH范围是0～23，mm和ss范围是0～59。输入这个条件，会查询出生效时间大于这个时间的记录。此参数不携带或携带值为空时，不作为筛选条件。
effective_time_end	否	String	最大长度：20	生效时间（结束）。 UTC时间，格式：yyyy-MM-dd'T'HH:mm:ss'Z'，如“2019-05-06T08:05:01Z”。其中，HH范围是0～23，mm和ss范围是0～59。输入这个条件，会查询出生效时间小于这个时间的记录。此参数不携带或携带值为空时，不作为筛选条件。
expire_time_begin	否	String	最大长度：20	失效时间（开始）。 UTC时间，格式：yyyy-MM-dd'T'HH:mm:ss'Z'，如“2019-05-06T08:05:01Z”。其中，HH范围是0～23，mm和ss范围是0～59。输入这个条件，会查询出失效时间大于这个时间的记录。此参数不携带或携带值为空时，不作为筛选条件。
expire_time_end	否	String	最大长度：20	失效时间（结束）。 UTC时间，格式：yyyy-MM-dd'T'HH:mm:ss'Z'，如“2019-05-06T08:05:01Z”。其中，HH范围是0～23，mm和ss范围是0～59。输入这个条件，会查询出失效时间小于这个时间的记录。此参数不携带或携带值为空时，不作为筛选条件。
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。
indirect_partner_id	否	String	最大长度：64	云经销商ID。获取方法请参见查询云经销商列表。华为云总经销商（一级经销商）查询云经销商发放给子客户的优惠券时，需要携带该参数；除此之外，此参数不做处理。否则只能查询发放给自己子客户的优惠券。

请求消息

请求参数

无。

请求示例

GET https://bss.myhuaweicloud.com/v2/promotions/benefits/partner-coupons?coupon_id=CP190912081601OJDA&customer_id=CS19040119281JMYC&order_id=promotionPlanId5322584&coupon_type=1&status=2&create_time_begin=2017-12-17T10:32:02Z&create_time_end=2017-12-17T10:32:02Z&effective_time_begin=2017-12-17T10:32:02Z&effective_time_end=2017-12-17T10:32:02Z&expire_time_begin=2017-12-17T10:32:02Z&expire_time_end=2017-12-17T10:32:02Z&offset=0&limit=10&indirect_partner_id=5c2ec3bd80c9462aad432f5566e9feb1 HTTP/1.1
Content-Type: application/json
X-Auth-Token：MIIPAgYJKoZIhvcNAQcCo...ggg1BBIINPXsidG9rZ

响应消息

响应参数

参数	参数类型	取值范围	描述
error_code	String	最大长度：20	状态码。具体请参见状态码。
error_msg	String	最大长度：1000	错误描述信息。
total_count	Integer	-	总数。
user_coupons	List< IQueryUserPartnerCouponsResult>	-	发放的优惠券记录。具体请参见表2。

表2 IQueryUserPartnerCouponsResult
参数	参数类型	描述
coupon_id	String	优惠券ID。
status	Integer	优惠券状态： 2：可使用 3：已使用 4：已过期 5：已回收
customer_id	String	客户账号ID。
coupon_type	Integer	优惠券类别： 1：代金券 4：现金券
measure_id	Integer	优惠券面额单位。 1：元。
face_value	BigDecimal	优惠券面值。
effective_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。
promotion_plan_name	String	促销计划名称。
promotion_plan_desc	String	促销计划描述。
media_type	Integer	介质类型。 1：电子券 2：纸质券
fetch_method	Integer	获取方式。 1：线上领取 2：线上兑换 3：线上发放 4：线下获取 5：事件赠送
use_limits	List<ICouponUseLimitInfoV2>	优惠券限制。具体请参见表3。
active_time	String	优惠券的激活时间。
last_used_time	String	优惠券的使用时间。
promotion_id	String	促销活动ID。
create_time	String	优惠券的创建时间。
balance	BigDecimal	优惠券余额。
lock_order_id	String	锁定优惠券的订单ID。如果为老版本优惠券，该值为空。
is_frozen	String	优惠券是否冻结。 0：否 1：是可用优惠券接口返回时不包括冻结状态的优惠券。

表3 ICouponUseLimitInfoV2
参数	参数类型	描述
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。

表4 ICouponUseLimitInfo的limit_key要求
key值	含义	说明	备注
baseValue	订单金额	value1中保存订单金额下限，value2中保存订单金额上限。	支持代金券，现金券，折扣券
serviceType	云服务类型	只有value1有效，具体的云服务类型请调用查询云服务类型列表接口获取。	支持代金券，现金券，折扣券
regionCode	区域编码	value2中保存区域名称，value1中保存区域编码。	支持代金券，现金券，折扣券
productId	产品ID	可以包含多个产品ID，英文逗号分隔。	支持代金券，现金券，折扣券
subscribeType	订购类型	只有value1有效。取值为：下单：new 续订：renew 变更：change	支持代金券，现金券，折扣券
firstOrderInService	首次购买限制	只有value1有效。	支持代金券，现金券，折扣券
cycleNum	周期数量	只有value1有效。	支持代金券，现金券，折扣券
cycleType	适用周期类型	0：包年/包月-不限 1：包年/包月-年 2：包年/包月-月 3：包年/包月-天 4：包年/包月-小时 5：按需 6：通用 7：一次性（只针对订购送事件活动） 8：预留实例 11：节省计划	支持代金券，现金券，折扣券，折扣券仅支持包年/包月
simultaneousUseWithEmpowerDiscount	代金券是否可以和授权折扣同享	代金券是否可以和授权折扣（包括商务折扣和伙伴授予折扣）同享。 0：否 1：是	支持代金券，现金券，折扣券，折扣券只能使用0。
usageTimes	是否支持多次使用	是否支持多次使用，值保存在value1中。取值为： 0：不限制次数 1：1次 N：限制使用N次（目前旧版代金券固定填写为1）	CouponType=折扣券时，只能设置为1；不指定或者指定为非1，均设置为1。 CouponType=代金券、现金券时，如果不指定或者指定为0、1之外的值，均设置为0。
isOnlyForStrictSelected	是否只能用于云商店严选产品	是否只能用于云商店严选产品，值保存在value1中。取值为： 0：否 1：是如果没有这个限制，等同于0；该限制只是用于现金券。	支持现金券
isRebate	是否参与伙伴激励返点	是否参与伙伴激励返点，值保存在value1中。取值为： 0：否 1：是该限制只是用于现金券。	支持现金券
serviceTypeBlackList	服务类型黑名单	服务类型黑名单，value1中保存服务类型编码；该限制只是用于现金券。	支持现金券
minConsumeDiscount	最低客户消费折扣	最低客户消费折扣，值保存在value1中。取值为0-1之间（不包括0和1）。	支持代金券、现金券
isForAnnualContracts	是否只能用于包年/包月1年的订单	是否只能用于包年/包月1年的订单。取值为： 0：否 1：是	支持代金券、折扣券
simultaneousUseWithPromotionProduct	是否可以和促销产品同享	代金券是否可以和促销产品同享，值保存在value1中。取值为： 0：否 1：是	支持代金券/折扣券
simultaneousUseWithPromotionDiscount	是否可以和促销折扣同享	代金券是否可以和促销折扣同享，值保存在value1中。取值为： 0：否 1：是	支持代金券
simultaneousUseWithDiscountCoupon	是否可以和折扣券同享	代金券是否可以和折扣券同享，值保存在value1中。取值为： 0：否 1：是	支持代金券

响应示例

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: length
Date: response time
{
    "total_count": 1,
    "user_coupons": [
        {
            "coupon_id": "CP200518080955A7LU",
            "status": 2,
            "customer_id": "051b9c187500d5340f0cc00f45000440",
            "coupon_type": 1,
            "measure_id": 1,
            "face_value": 1.11,
            "effective_time": "2020-04-08T08:53:05Z",
            "expire_time": "2021-04-30T15:59:59Z",
            "order_id": null,
            "promotion_plan_id": null,
            "promotion_plan_name": "华为云产品代金券",
            "promotion_plan_desc": null,
            "media_type": null,
            "fetch_method": null,
            "use_limits": [
                {
                    "use_limiti_info_id": null,
                    "limit_key": "simultaneousUseWithPromotionProduct",
                    "value1": "1",
                    "value2": null,
                    "value_unit": null,
                    "limit_type": "=",
                    "promotion_plan_id": null
                },
                {
                    "use_limiti_info_id": null,
                    "limit_key": "cycleType",
                    "value1": "1|2|5",
                    "value2": null,
                    "value_unit": null,
                    "limit_type": "=",
                    "promotion_plan_id": null
                },
                {
                    "use_limiti_info_id": null,
                    "limit_key": "cycleNum",
                    "value1": "2,1,3||",
                    "value2": null,
                    "value_unit": null,
                    "limit_type": "in",
                    "promotion_plan_id": null
                },
                {
                    "use_limiti_info_id": null,
                    "limit_key": "couponClass",
                    "value1": "0",
                    "value2": null,
                    "value_unit": null,
                    "limit_type": "=",
                    "promotion_plan_id": null
                },
                {
                    "use_limiti_info_id": null,
                    "limit_key": "simultaneousUseWithDiscountCoupon",
                    "value1": "1",
                    "value2": null,
                    "value_unit": null,
                    "limit_type": "=",
                    "promotion_plan_id": null
                },
                {
                    "use_limiti_info_id": null,
                    "limit_key": "simultaneousUseWithPromotionDiscount",
                    "value1": "1",
                    "value2": null,
                    "value_unit": null,
                    "limit_type": "=",
                    "promotion_plan_id": null
                },
                {
                    "use_limiti_info_id": null,
                    "limit_key": "usageTimes",
                    "value1": "0",
                    "value2": null,
                    "value_unit": null,
                    "limit_type": "=",
                    "promotion_plan_id": null
                },
                {
                    "use_limiti_info_id": null,
                    "limit_key": "simultaneousUseWithEmpowerDiscount",
                    "value1": "1",
                    "value2": null,
                    "value_unit": null,
                    "limit_type": "=",
                    "promotion_plan_id": null
                },
                {
                    "use_limiti_info_id": "CP200518080955A7LU",
                    "limit_key": "serviceTypeBlackList",
                    "value1": "hws.service.type.webscan,hws.service.type.cpts6",
                    "value2": null,
                    "value_unit": null,
                    "limit_type": null,
                    "promotion_plan_id": null
                }
            ],
            "active_time": "2020-05-18T08:09:55Z",
            "last_used_time": null,
            "promotion_id": null,
            "create_time": "2020-05-18T08:09:55Z",
            "balance": 1.11,
            "lock_order_id": "",
            "is_frozen": "0"
        }
    ]
}

状态码

状态码4xx：由于明显的客户端错误（例如，格式错误的请求语法、参数错误等），华为云会返回4xx错误码，请及时检查请求消息的正确性，重新发起请求。
状态码5xx：由于华为云系统原因，导致无法完成明显有效请求的处理，可及时联系华为云客服处理。

HTTP状态码	错误码	描述
400	CBC.0100	参数错误。
400	CBC.99000037	您没有操作该云经销商的权限。
403	CBC.0151	访问拒绝。
500	CBC.0999	其他错误。

父主题： 管理优惠券

上一篇：回收优惠券

下一篇：查询优惠券的发放回收记录

意见反馈

文档内容是否对您有帮助？

有帮助没帮助

提供反馈

提交成功！非常感谢您的反馈，我们会继续努力做到更好！您可在我的云声建议查看反馈及问题处理状态。

系统繁忙，请稍后重试

在使用文档中是否遇到以下问题

内容与产品页面不一致

内容不易理解

缺失示例代码

步骤不可操作

搜不到想要的内容

缺少最佳实践

意见反馈（选填）

0/500

请至少选择一项反馈信息并填写问题反馈

字符长度不能超过500

直接提交取消

如您有其它疑问，您也可以通过华为云社区问答频道来与我们联系探讨

智能客服提问云社区提问

查询已发放的优惠券

功能介绍

接口约束

调试

URI

请求消息

响应消息

状态码

相关文档

意见反馈

文档内容是否对您有帮助？

7*24

备案

专业服务

退订

建议反馈

售前咨询热线