> ## Documentation Index > Fetch the complete documentation index at: https://docs.fluz.app/llms.txt > Use this file to discover all available pages before exploring further. # 绑定卡优惠 本页详细介绍如何使用 `getMerchants` 查询来检索和理解绑定卡优惠（CLOs）。CLO 通过 `type` 字段值 `CARD_LINKED_OFFER` 来标识，且通常与 Fluz 虚拟卡 的使用相关——有时只能通过它兑换。它们使用独立的结构 `cloDetails` 来表示费率和条件信息，与标准 礼品卡 优惠有显著不同。 **先决条件：** 具有 `LIST_OFFERS` 范围的用户访问令牌。完整查询契约：[API 参考](https://storage.googleapis.com/fluz-public-docs/api-reference.html#query-getMerchants)。 若仅获取 CLO，请将 `offerTypes` 输入参数设置为 `{ cardLinkedOffer: true, giftCardOffer: false }`。 ## 绑定卡优惠的详细查询 该查询请求与 CLO 特别相关的字段，重点关注 `cloDetails` 对象。对于 CLO，像 `offerRates` 和 `stockInfo` 等与 礼品卡 相关的字段通常为 `null` 或为空，查询 CLO 时通常可省略。 ```graphql theme={null} query GetCLOMerchants( $name: String, $paginate: OffsetInput, $offerTypes: OfferTypesInput ) { getMerchants( name: $name, paginate: $paginate, offerTypes: $offerTypes ) { merchantId name slug offers { offerId type # Will be CARD_LINKED_OFFER hasStockInfo # Usually false for CLOs denominationsType # Often VARIABLE for CLOs # --- Offer Rates (Usually null/empty for CLOs) --- # offerRates { maxUserRewardValue } # Can query, but expect null # --- Stock Info (Usually null/empty for CLOs) --- # stockInfo { ... on StockInfoVariableType { __typename } } # Usually empty # --- CLO Details (Relevant for CLOs) --- cloDetails { currentRateType regularRate promoRate promoBaseRate promoMaxCap applyPromoBaseRateAfterCap minimumPurchaseAmount activePeriodStartDate activePeriodEndDate periods { id offerRateType periodType startDate endDate startTime endTime daysOfWeek daysOfMonth } } } } } # Example Variables to pass with the query: # { # "paginate": { "limit": 20, "offset": 0 }, # "offerTypes": { "cardLinkedOffer": true, "giftCardOffer": false } # } ``` ## 示例响应 以下是使用 `getMerchants` 查询且仅包含 CLO 优惠时将获得的示例响应： ```json JSON theme={null} { "data": { "getMerchants": [ { "merchantId": "4b4195cb-ba98-49e6-8935-761458a76cdd", "name": "REI", "slug": "REI", "offers": [ { "offeringMerchantId": "4b4195cb-ba98-49e6-8935-761458a76cdd", "offerId": "3edd79b7-aa46-4bd6-96de-b78e4f3a79e0", "type": "CARD_LINKED_OFFER", "hasStockInfo": false, "denominationsType": "VARIABLE", "stockInfo": [], "offerRates": null, "cloDetails": { "currentRateType": "PROMO", "regularRate": 22, "promoRate": 25, "promoBaseRate": 20, "promoMaxCap": 1523, "applyPromoBaseRateAfterCap": false, "minimumPurchaseAmount": null, "activePeriodStartDate": null, "activePeriodEndDate": null, "periods": [ { "id": "0cb1fde3-cfb5-4f31-b75f-eedf55d65ca7", "offerRateType": "PROMO", "periodType": "ALWAYS_AVAILABLE", "startDate": null, "endDate": null, "startTime": null, "endTime": null, "daysOfWeek": null, "daysOfMonth": null }, { "id": "21f57686-4139-4392-8eca-00cffad24fa1", "offerRateType": "REGULAR", "periodType": "ALWAYS_AVAILABLE", "startDate": null, "endDate": null, "startTime": null, "endTime": null, "daysOfWeek": null, "daysOfMonth": null } ] } }, { "offeringMerchantId": "4b4195cb-ba98-49e6-8935-761458a76cdd", "offerId": "7ec04538-ad28-4d49-8181-f4ec108facc1", "type": "CARD_LINKED_OFFER", "hasStockInfo": false, "denominationsType": "VARIABLE", "stockInfo": [], "offerRates": null, "cloDetails": { "currentRateType": "PROMO", "regularRate": 4, "promoRate": 17, "promoBaseRate": 12, "promoMaxCap": 1999, "applyPromoBaseRateAfterCap": false, "minimumPurchaseAmount": null, "activePeriodStartDate": "2025-04-21", "activePeriodEndDate": "2025-04-27", "periods": [ { "id": "9f887399-7bd6-44ad-af04-3fccdafeb092", "offerRateType": "PROMO", "periodType": "MULTIPLE_DAYS", "startDate": "2025-04-21", "endDate": "2025-04-27", "startTime": null, "endTime": null, "daysOfWeek": null, "daysOfMonth": null }, { "id": "3769f838-f0a8-4971-9415-6bb15eae64be", "offerRateType": "REGULAR", "periodType": "ALWAYS_AVAILABLE", "startDate": null, "endDate": null, "startTime": null, "endTime": null, "daysOfWeek": null, "daysOfMonth": null } ] } } ] } ] } } ``` ## 绑定卡优惠特定字段说明 当 `offer.type` 为 `CARD_LINKED_OFFER` 时，主要信息来源是 `Offer` 内的 `cloDetails` 对象。 * **`type`** (`String!`)：始终为 `CARD_LINKED_OFFER`。 * **`cloDetails`** (`CloDetails`)：该复杂对象包含绑定卡优惠的所有具体费率、促销、时间规则和条件。对于非 CLO 类型返回 `null`。其字段拆解见下表。 * **`offerRates`**：对 CLO 通常为 `null` 或空。费率信息包含在 `cloDetails` 中。 * **`stockInfo`**：对 CLO 通常为空，因为它们通常与用卡行为相关，而非预定义库存。 * **`hasStockInfo`**：对 CLO 通常为 `false`。 * **`denominationsType`**：对 CLO 通常为 `VARIABLE`，反映该优惠适用于交易金额而非固定 礼品卡 面额。 ### 理解 `CloDetails` 对象 此对象提供绑定卡优惠的具体费率结构。 | 字段名 | 类型 | 描述 | | :--------------------------- | :--------------- | :------------------------------------------------------------------------------------------------------------- | | `currentRateType` | CloRateTypeEnum! | 表示当前激活的是 `REGULAR` 还是 `PROMO` 费率，由针对当前时间评估所有 `periods` 决定。（`REGULAR`、`PROMO`） | | `regularRate` | Float | 当没有促销活动时适用的标准奖励费率。 | | `promoRate` | Float | 当 `PROMO` 时段激活且购买金额小于或等于 `promoMaxCap`（如适用）时适用的促销奖励费率。 | | `promoBaseRate` | Float | 在 `PROMO` 时段下，超过 `promoMaxCap` 之后适用的奖励费率，前提是 `applyPromoBaseRateAfterCap` 为 true。 | | `promoMaxCap` | Float | 在 `PROMO` 时段内 `promoRate` 适用的最高购买金额（货币数值）。超过该金额的部分可能获得 `promoBaseRate` 或 `regularRate`，取决于标志位。 | | `applyPromoBaseRateAfterCap` | Boolean | 若为 `true`，在 `PROMO` 时段内，对超过 `promoMaxCap` 的购买金额部分应用 `promoBaseRate`。若为 `false`，超出部分可能不获得奖励或按 `regularRate` 计算。 | | `minimumPurchaseAmount` | Float | 获得此 CLO 任意奖励所需的最低交易金额（如有）。 | | `activePeriodStartDate` | String | 若当前激活的优惠时段（可能是常规或促销）定义了起止日期，则为其开始日期（YYYY-MM-DD）。若始终有效或基于其他条件，则为 `null`。 | | `activePeriodEndDate` | String | 若适用，为当前激活优惠时段的结束日期（YYYY-MM-DD）。若始终有效或开放式，则为 `null`。 | | `periods` | \[CloPeriod!]! | 与此优惠关联的所有已定义时间段列表。系统评估这些时间段以确定 `currentRateType`。参见下方 `CloPeriod` 表。 | ### 理解 `CloPeriod` 对象（位于 `CloDetails.periods` 内） `periods` 数组中的每个对象定义一个特定的时间窗口及其关联的费率类型（`REGULAR` 或 `PROMO`）。这些时间段的组合决定了优惠的可用性和激活费率。 | 字段名 | 类型 | 描述 | | :-------------- | :--------------- | :------------------------------------------------------------------------------------ | | `id` | UUID! | 此特定时间段定义的唯一标识符。 | | `offerRateType` | CloRateTypeEnum! | 表示该时间段对应于父级 `CloDetails` 中定义的 `REGULAR` 或 `PROMO` 费率结构。 | | `periodType` | String | 描述该时间段的时间性质（例如，`ALWAYS_AVAILABLE`、`MULTIPLE_DAYS`、`SPECIFIC_DAY`、`RECURRING_WEEKLY`）。 | | `startDate` | String | 该时间段规则可能生效的开始日期（YYYY-MM-DD）。 | | `endDate` | String | 该时间段规则停止生效的结束日期（YYYY-MM-DD）。 | | `startTime` | String | 每日适用的开始时间（例如 UTC 或定义时区的 "HH:MM"），常与 `daysOfWeek` 搭配使用。 | | `endTime` | String | 每日适用的结束时间（例如 UTC 或定义时区的 "HH:MM"）。 | | `daysOfWeek` | \[String] | 一周中该时间段规则生效的日期数组（例如，\["MONDAY", "FRIDAY"]）。用于每周循环的时间段。 | | `daysOfMonth` | \[String] | 每月中特定日期数组（例如，\["1", "15"]）表示该时间段规则生效的日期。用于每月循环的时间段。 | ## 后续步骤 发行这些优惠所奖励的卡片——CLO 返现适用于其消费。 调整现有卡片的限额、资金来源和生命周期设置。