> ## 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. # 連結卡優惠（Card Linked Offers） 本頁說明如何使用 `getMerchants` 查詢以擷取並理解連結卡優惠（CLOs）。CLO 會以 `type` 欄位值 `CARD_LINKED_OFFER` 辨識，且經常與 Fluz 虛擬卡的使用相關——有時僅能透過虛擬卡兌換。它們使用名為 `cloDetails` 的獨立結構來呈現費率與條件資訊，與標準禮品卡優惠有顯著差異。 **必要條件：** 具備 `LIST_OFFERS` 範圍的使用者存取權杖。完整查詢合約： [API Reference](https://storage.googleapis.com/fluz-public-docs/api-reference.html#query-getMerchants)。 若要只抓取 CLO，將 `offerTypes` 輸入參數設為 `{ cardLinkedOffer: true, giftCardOffer: false }`。 ## 連結卡優惠的詳細查詢 此查詢請求特別與 CLO 相關的欄位，重點放在 `cloDetails` 物件。像是 `offerRates` 與 `stockInfo` 這類與禮品卡相關的欄位，在 CLO 中通常為 `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 } # } ``` ## 範例回應 以下是以僅包含 CLO 優惠為條件呼叫 `getMerchants` 查詢時的回應範例： ```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` 物件 此物件提供連結卡優惠的特定費率結構。 | 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，可能是 regular 或 promo），若該生效期間有定義起迄日期。若為常時生效或依其他準則，則為 `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 | 每日適用的開始時間（例如 "HH:MM"，以 UTC 或定義的時區），常與 `daysOfWeek` 搭配使用。 | | `endTime` | String | 每日適用的結束時間（例如 "HH:MM"，以 UTC 或定義的時區）。 | | `daysOfWeek` | \[String] | 此期間規則在每週哪些日子生效的陣列（例如 \["MONDAY", "FRIDAY"]）。用於每週循環的期間。 | | `daysOfMonth` | \[String] | 此期間規則在每月哪些特定日期生效的陣列（例如 \["1", "15"]）。用於每月循環的期間。 | ## 後續步驟 發卡以承接此類優惠的回饋——CLO 的收益會套用於其消費。 調整現有卡片的限額、資金與生命週期設定。