卡片关联优惠

本页介绍如何使用 getMerchants 查询来获取和理解卡片关联优惠（CLO）。CLO 通过 type 字段值 CARD_LINKED_OFFER 进行标识，通常与 Fluz 虚拟卡的使用相关联——有时仅能通过该卡兑换。它们使用一种独特的结构 cloDetails 来存储费率和条件信息，这与标准礼品卡优惠有显著不同。

前提条件： 具有 LIST_OFFERS 权限范围的用户访问令牌。完整查询规范：API 参考文档。

若要仅获取 CLO，请将 offerTypes 输入参数设置为 { cardLinkedOffer: true, giftCardOffer: false }。

卡片关联优惠详细查询

此查询请求与 CLO 特别相关的字段，重点关注 cloDetails 对象。像 offerRates 和 stockInfo 这类与礼品卡相关的字段，对 CLO 而言通常为 null 或为空，因此在查询 CLO 时通常可以省略。

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 {
          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 }
# }

此查询消耗 7,000 点查询成本上限中的 6,396 点。periods 下的每个字段都会消耗 625 点，因此添加其中任意一个字段（例如下表中的 id）或取消注释 stockInfo 行，都会使查询超出查询成本限制。默认会为每个选择集添加 __typename 的客户端（如 Apollo Client）同样会导致超出限制。请在单独的查询中获取其他字段。

示例响应

以下是仅包含 CLO 优惠时，getMerchants 查询返回的示例响应：

JSON

{
  "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": [
                {
                  "offerRateType": "PROMO",
                  "periodType": "ALWAYS_AVAILABLE",
                  "startDate": null,
                  "endDate": null,
                  "startTime": null,
                  "endTime": null,
                  "daysOfWeek": null,
                  "daysOfMonth": null
                },
                {
                  "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": [
                {
                  "offerRateType": "PROMO",
                  "periodType": "MULTIPLE_DAYS",
                  "startDate": "2025-04-21",
                  "endDate": "2025-04-27",
                  "startTime": null,
                  "endTime": null,
                  "daysOfWeek": null,
                  "daysOfMonth": null
                },
                {
                  "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` 对象

此对象提供卡片关联优惠的具体费率结构。

Field Name	Type	Description
`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）。这些时段的组合共同决定了该优惠的可用性和生效费率。

Field Name	Type	Description
`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 收益。

编辑虚拟卡

调整现有卡片的限额、资金和生命周期设置。

​卡片关联优惠详细查询

​示例响应

​卡片关联优惠专属字段说明

​理解 CloDetails 对象

​理解 CloPeriod 对象（位于 CloDetails.periods 内）

​后续步骤

创建虚拟卡

编辑虚拟卡

卡片关联优惠详细查询

示例响应

卡片关联优惠专属字段说明

理解 `CloDetails` 对象

理解 `CloPeriod` 对象（位于 `CloDetails.periods` 内）

后续步骤