卡片連結優惠

本頁說明如何使用 getMerchants 查詢來取得並了解卡片連結優惠 (CLO)。CLO 可透過 type 欄位值 CARD_LINKED_OFFER 識別，且通常與 Fluz 虛擬卡的使用相關聯，有時甚至僅能透過該卡兌換。CLO 使用獨立的 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 通常為空值，因為 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”]），用於每月重複的期間。

功能

卡片連結優惠

卡片連結優惠的詳細查詢

回應範例

卡片連結優惠專屬欄位說明

了解 `CloDetails` 物件

了解 `CloPeriod` 物件（位於 `CloDetails.periods` 中）

後續步驟

建立虛擬卡

編輯虛擬卡

​卡片連結優惠的詳細查詢

​回應範例

​卡片連結優惠專屬欄位說明

​了解 CloDetails 物件

​了解 CloPeriod 物件（位於 CloDetails.periods 中）

​後續步驟

建立虛擬卡

編輯虛擬卡

卡片連結優惠的詳細查詢

回應範例

卡片連結優惠專屬欄位說明

了解 `CloDetails` 物件

了解 `CloPeriod` 物件（位於 `CloDetails.periods` 中）

後續步驟