getMerchants 查詢以擷取並理解連結卡優惠（CLOs）。CLO 會以 type 欄位值 CARD_LINKED_OFFER 辨識，且經常與 Fluz 虛擬卡的使用相關——有時僅能透過虛擬卡兌換。它們使用名為 cloDetails 的獨立結構來呈現費率與條件資訊，與標準禮品卡優惠有顯著差異。
必要條件： 具備
LIST_OFFERS 範圍的使用者存取權杖。完整查詢合約： API Reference。若要只抓取 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 {
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
{
"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 的收益會套用於其消費。
編輯虛擬卡
調整現有卡片的限額、資金與生命週期設定。