取得禮品卡優惠

所需 Scope： LIST_OFFERS (API 參考連結) 本頁說明如何使用 getMerchants 查詢來擷取並理解禮品卡優惠。禮品卡優惠通常包含 GIFT_CARD_OFFER 與 EXCLUSIVE_RATE_OFFER 等類型。若只要擷取禮品卡優惠，請將 offerTypes 輸入參數設為 { giftCardOffer: true, cardLinkedOffer: false }。

禮品卡優惠的詳細查詢

此查詢會請求與禮品卡特別相關的欄位，包括回饋率（offerRates）與庫存可用性（stockInfo）。 範例請求：

# Define the query with variables
query GetGiftCardMerchants(
  $name: String,
  $paginate: OffsetInput,
  $offerTypes: OfferTypesInput  # Define the input type for offerTypes (optional)
) {
  getMerchants(
    name: $name,
    paginate: $paginate,
    offerTypes: $offerTypes  # Pass the variable here (optional)
  ) {
    merchantId
    name
    slug
    logoUrl        # Merchant logo image URL
    faceplateUrl   # Rectangular card art/faceplate image URL
    shortDescription   # Short marketing description of the merchant

    offers {
      offerId
      exclusiveRateId   # Optional, only returns for type = EXCLUSIVE_RATE_OFFER
      type
      deliveryFormat    # How the gift card will be delivered (URL, CODES, etc.)
      barcodeType       # Barcode format (NONE, C128, PDF417, QRCODE)
      hasStockInfo
      denominationsType # FIXED or VARIABLE
      termsAndConditions # Offer T&C text (legal language, restrictions, expiration)

      # --- Offer Rates (Relevant for Gift Cards) ---
      offerRates {
        maxUserRewardValue
        cashbackVoucherRewardValue
        boostRewardValue
        displayBoostReward
        denominations
        allowedPaymentMethods
      }

      # --- Stock Info (Relevant for Gift Cards) ---
      stockInfo {
        ... on StockInfoVariableType {
          __typename
          description
          maxDenomination
          minDenomination
        }
        ... on StockInfoFixedType {
          __typename
          denomination
          availableStock
        }
      }

      # --- CLO Details (Will be null for Gift Cards) ---
      # cloDetails { currentRateType }  # Can query, but expect null
    }
  }
}

# Example Variables to pass with the query:
# {
#   "paginate": { "limit": 20, "offset": 0 },
#   "offerTypes": { "giftCardOffer": true, "cardLinkedOffer": false }
# }

請注意由於速率限制，你可能需要分頁並多次呼叫商家列表。

範例回應（當僅篩選禮品卡優惠時）：

回應會包含多個商家，但每個商家的 offers 陣列只會包含符合 offerTypes 篩選條件的優惠（此例為禮品卡優惠）。

JSON

{
  "data": {
    "getMerchants": [
      {
        "merchantId": "123e4567-e89b-12d3-a456-426614174000",
        "name": "Best Buy",
        "slug": "best-buy",
        "logoUrl": "https://storage.googleapis.com/.../best-buy-logo.jpg",
        "faceplateUrl": "https://storage.googleapis.com/.../best-buy-faceplate.png",
        "shortDescription": "America's leading destination for tech, gadgets, and home electronics.",
        "offers": [
          {
            "offeringMerchantId": "255f8245-02c7-4817-901e-15fe265f6968",
            "offerId": "1a2b3c4d-5e6f-7g8h-9i10-jk11l12m13n14",
            "exclusiveRateId": null,
            "type": "GIFT_CARD_OFFER",
            "deliveryFormat": "CODES",
            "barcodeType": "C128",
            "hasStockInfo": true,
            "offerRates": [
              {
                "maxUserRewardValue": 50.0,
                "cashbackVoucherRewardValue": 5.0,
                "boostRewardValue": 10.0,
                "displayBoostReward": true,
                "denominations": ["10", "500"],
                "allowedPaymentMethods": ["CREDIT_CARD", "DEBIT_CARD"]
              }
            ],
            "denominationsType": "FIXED",
            "termsAndConditions": "Card valid only at Best Buy U.S. retail stores and BestBuy.com. Cannot be used to purchase other gift cards. Not redeemable for cash except where required by law.",
            "stockInfo": [
              {
                "__typename": "StockInfoFixedType",
                "denomination": 500,
                "availableStock": 200
              }
            ]
          }
        ]
      },
      {
        "merchantId": "223e4567-e89b-12d3-a456-426614174001",
        "name": "H&M",
        "slug": "h&m",
        "logoUrl": "https://storage.googleapis.com/.../hm-logo.jpg",
        "faceplateUrl": null,
        "shortDescription": "Affordable fashion for women, men, and kids — from staples to seasonal collections.",
        "offers": [
          {
            "offeringMerchantId": "3c7b4d5e-6f7g-8h9i-10jk-11l12m13n14o",
            "offerId": "2a2b3c4d-5e6f-7g8h-9i10-jk11l12m13n15",
            "exclusiveRateId": "0c8e6beb-5d62-4a0c-ae94-b889395f1e2d",
            "type": "EXCLUSIVE_RATE_OFFER",
            "deliveryFormat": "URL",
            "barcodeType": "NONE",
            "hasStockInfo": false,
            "offerRates": [
              {
                "maxUserRewardValue": 30.0,
                "cashbackVoucherRewardValue": 3.0,
                "boostRewardValue": 8.0,
                "displayBoostReward": false,
                "denominations": ["20", "50", "100"],
                "allowedPaymentMethods": ["CREDIT_CARD", "PAYPAL"]
              }
            ],
            "denominationsType": "FIXED",
            "termsAndConditions": "Redeemable online at hm.com or any H&M retail store in the U.S. Cannot be redeemed for cash except where required by law.",
            "stockInfo": []
          }
        ]
      }
    ]
  }
}

理解 ‘Offers’ 陣列：

Merchant 物件中的 offers 欄位包含一個 Offer 物件陣列。該 offer 物件包含 Fluz 目錄中商家可用之特定優惠的相關資訊。以下是所包含的欄位：

理解 ‘Offer rate’：

OfferRate 物件代表與優惠相關的特定回饋率與條件。此物件包含使用者在使用優惠時可獲得的回饋詳細資訊，以及這些回饋適用之條件：

欄位名稱	型別	說明
maxUserRewardValue	Float	使用者可獲得的現金回饋上限。此欄位定義了針對特定優惠可賺取之回饋金額的最高限制。
cashbackVoucherRewardValue	Float	在優惠套用加成後的現金回饋值。通常為你前 $10 消費可獲得 25% 的現金回饋加成。
boostRewardValue	Float	當優惠的現金回饋數值被提高時，會顯示在此。這些加成是於一段期間內提供給使用者的額外誘因。
displayBoostReward	Boolean	指示是否應向使用者顯示加成回饋。此欄位用於控制在使用者介面中加成回饋的可見性。
denominations	[String]	符合此優惠的面額陣列。這些面額代表適用的特定金額（例如 “10”、“25”、“50”），用以定義可獲得回饋的金額範圍。
allowedPaymentMethods	[String]	此優惠允許使用的付款方式陣列。此欄位指定使用者可使用哪些付款方式（例如 “CREDIT_CARD”、“PAYPAL”）來享受此優惠。

​禮品卡優惠的詳細查詢

​範例回應（當僅篩選禮品卡優惠時）：

​理解 ‘Offers’ 陣列：

​理解 ‘Offer rate’：

禮品卡優惠的詳細查詢

範例回應（當僅篩選禮品卡優惠時）：

理解 ‘Offers’ 陣列：

理解 ‘Offer rate’：