> ## 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.

# 取得禮品卡優惠

**所需 Scope：** `LIST_OFFERS` ([API 參考連結](https://storage.googleapis.com/fluz-public-docs/api-reference.html#query-getMerchants))

本頁說明如何使用 `getMerchants` 查詢來擷取並理解禮品卡優惠。禮品卡優惠通常包含 `GIFT_CARD_OFFER` 與 `EXCLUSIVE_RATE_OFFER` 等類型。

若只要擷取禮品卡優惠，請將 `offerTypes` 輸入參數設為 `{ giftCardOffer: true, cardLinkedOffer: false }`。

## 禮品卡優惠的詳細查詢

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

**範例請求：**

```graphql theme={null}
# 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 }
# }
```

<Callout icon="📘">
  請注意由於速率限制，你可能需要分頁並多次呼叫商家列表。
</Callout>

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

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

```json JSON theme={null}
{
  "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 目錄中商家可用之特定優惠的相關資訊。以下是所包含的欄位：

<Table align={["left","left","left"]}>
  <thead>
    <tr>
      <th>
        欄位名稱
      </th>

      <th>
        型別
      </th>

      <th>
        說明
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        offeringMerchantId
      </td>

      <td>
        UUID!
      </td>

      <td>
        提供該特定交易或折扣之商家的唯一識別碼。此為必填欄位，且必須為有效的 UUID。
      </td>
    </tr>

    <tr>
      <td>
        offerId
      </td>

      <td>
        UUID!
      </td>

      <td>
        優惠本身的唯一識別碼。
      </td>
    </tr>

    <tr>
      <td>
        exclusiveRateId
      </td>

      <td>
        UUID
      </td>

      <td>
        該優惠的 exclusive\_rate\_id。僅在 type = EXCLUSIVE\_RATE\_OFFER 時回傳。此值可傳入 purchaseGiftCard 以指定你想使用的專屬費率。
      </td>
    </tr>

    <tr>
      <td>
        type
      </td>

      <td>
        String!
      </td>

      <td>
        指出優惠的類型。可能是標準禮品卡優惠或專屬費率優惠。
      </td>
    </tr>

    <tr>
      <td>
        deliveryFormat
      </td>

      <td>
        DeliveryFormatType
      </td>

      <td>
        指定禮品卡將如何交付給使用者。可能值：URL、CODES、PIN\_AS\_CODE、PIN\_WITH\_URL、CODE\_WITH\_PREFIX。這決定了使用者收到與兌換禮品卡的方式。
      </td>
    </tr>

    <tr>
      <td>
        barcodeType
      </td>

      <td>
        BarcodeTypeEnum
      </td>

      <td>
        指定此優惠的條碼格式。可能值：NONE（無條碼—可考慮顯示 faceplateUrl）、C128（Code 128）、PDF417、QRCODE。用於判斷是否需在你的 UI 中渲染條碼。
      </td>
    </tr>

    <tr>
      <td>
        hasStockInfo
      </td>

      <td>
        Boolean
      </td>

      <td>
        指出此優惠是否包含庫存資訊。若為 true，則 stockInfo 欄位會填入可用的面額。
      </td>
    </tr>

    <tr>
      <td>
        offerRates
      </td>

      <td>
        \[OfferRate]
      </td>

      <td>
        代表與優惠相關的特定回饋率與條件。
      </td>
    </tr>

    <tr>
      <td>
        denominationsType
      </td>

      <td>
        OfferDenominationType
      </td>

      <td>
        定義此優惠可用的面額型態。此欄位用以指定優惠金額的結構，例如固定或可變面額。
      </td>
    </tr>

    <tr>
      <td>
        termsAndConditions
      </td>

      <td>
        String
      </td>

      <td>
        此優惠的條款與細則文字（法律用語、限制、有效期限政策）。在使用者購買禮品卡前，請使用此內容向其顯示 T\&C。
      </td>
    </tr>

    <tr>
      <td>
        stockInfo
      </td>

      <td>
        \[StockInfoType]!
      </td>

      <td>
        StockInfo 是特定優惠可用面額的清單。僅在優惠的 hasStockInfo 為真時可用。這需要 Fluz 向供應商確認庫存，回應時間會依供應商而異。stockInfo 會依 `VARIABLE` 或 `FIXED` 型態有條件地回傳資訊。若要查詢 stockInfo，你需要使用 `... on` 關鍵字的 inline fragment。當面額型態為 `VARIABLE` 時回傳 `StockInfoVariableType`，為 `FIXED` 時回傳 `StockInfoFixedType`。

        更多詳細資訊，請參考 [GraphQL API 的運作方式](/concepts/graphql) 一文。
      </td>
    </tr>
  </tbody>
</Table>

### 理解 'Offer rate'：

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

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

<br />

<StickyContactSalesBanner />