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

# 获取礼品卡优惠

**所需权限范围：** `LIST_OFFERS` ([API Reference Link](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。可据此决定是否在您的界面中渲染条码。
      </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 为 true 时可用。这需要 Fluz 确认库存，响应时间因供应商而异。stockInfo 字段将根据 `VARIABLE` 或 `FIXED` 类型有条件返回信息。查询 stockInfo 时，需要使用内联片段并使用 `... on` 关键字。若面额类型为 `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 />