绑定卡优惠

本页详细介绍如何使用 getMerchants 查询来检索和理解绑定卡优惠（CLOs）。CLO 通过 type 字段值 CARD_LINKED_OFFER 来标识，且通常与 Fluz 虚拟卡的使用相关——有时只能通过它兑换。它们使用独立的结构 cloDetails 来表示费率和条件信息，与标准礼品卡优惠有显著不同。

先决条件： 具有 LIST_OFFERS 范围的用户访问令牌。完整查询契约：API 参考。

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

绑定卡优惠的详细查询

该查询请求与 CLO 特别相关的字段，重点关注 cloDetails 对象。对于 CLO，像 offerRates 和 stockInfo 等与礼品卡相关的字段通常为 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 {
          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

{
  "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”]）表示该时间段规则生效的日期。用于每月循环的时间段。

功能

绑定卡优惠的详细查询

示例响应

绑定卡优惠特定字段说明

理解 `CloDetails` 对象

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

后续步骤

创建虚拟卡

编辑虚拟卡

​绑定卡优惠的详细查询

​示例响应

​绑定卡优惠特定字段说明

​理解 CloDetails 对象

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

​后续步骤

创建虚拟卡

编辑虚拟卡

绑定卡优惠的详细查询

示例响应

绑定卡优惠特定字段说明

理解 `CloDetails` 对象

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

后续步骤