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

# Get Gift Card Offers

**Scope Required:** `LIST_OFFERS` ([API Reference Link](https://storage.googleapis.com/fluz-public-docs/api-reference.html#query-getMerchants))

This page details how to retrieve and understand Gift Card Offers using the `getMerchants` query. Gift Card offers typically include types like `GIFT_CARD_OFFER` and `EXCLUSIVE_RATE_OFFER`.

To fetch *only* Gift Card offers, use the `offerTypes` input argument set to `{ giftCardOffer: true, cardLinkedOffer: false }`.

## Detailed Query for Gift Card Offers

This query requests fields specifically relevant to Gift Cards, including reward rates (`offerRates`) and stock availability (`stockInfo`).

**Sample Request:**

```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="📘">
  Please note that due to rate-limiting, you might need to paginate and call the merchants list a few times.
</Callout>

## Sample Response (When Filtering for Gift Card Offers):

The response will contain merchants, but the offers array for each merchant will only include offers matching the offerTypes filter (in this case, Gift Card Offers).

```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": []
          }
        ]
      }
    ]
  }
}
```

### Understanding the 'Offers' array:

The offers field within the `Merchant` object contains an array of `Offer` objects. The offer object contains information about specific offers available from merchants in the Fluz catalog. Below are the fields included:

<Table align={["left","left","left"]}>
  <thead>
    <tr>
      <th>
        Field Name
      </th>

      <th>
        Type
      </th>

      <th>
        Description
      </th>
    </tr>
  </thead>

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

      <td>
        UUID!
      </td>

      <td>
        A unique identifier for the merchant offering the specific deal or discount. This is a required field and must be a valid UUID.
      </td>
    </tr>

    <tr>
      <td>
        offerId
      </td>

      <td>
        UUID!
      </td>

      <td>
        A unique identifier for the offer itself.
      </td>
    </tr>

    <tr>
      <td>
        exclusiveRateId
      </td>

      <td>
        UUID
      </td>

      <td>
        The exclusive\_rate\_id for the offer. Only returned for type = EXCLUSIVE\_RATE\_OFFER. This value can be passed in to purchaseGiftCard to specify the exclusive rate you want to purchase with.
      </td>
    </tr>

    <tr>
      <td>
        type
      </td>

      <td>
        String!
      </td>

      <td>
        Indicates the type of the offer. This could be a standard gift card offer or an exclusive rate offer.
      </td>
    </tr>

    <tr>
      <td>
        deliveryFormat
      </td>

      <td>
        DeliveryFormatType
      </td>

      <td>
        Specifies how the gift card will be delivered to the user. Possible values: URL, CODES, PIN\_AS\_CODE, PIN\_WITH\_URL, CODE\_WITH\_PREFIX. This determines how the user will receive and redeem the gift card.
      </td>
    </tr>

    <tr>
      <td>
        barcodeType
      </td>

      <td>
        BarcodeTypeEnum
      </td>

      <td>
        Specifies the barcode format for this offer. Possible values: NONE (no barcode - consider displaying faceplateUrl instead), C128 (Code 128), PDF417, QRCODE. Use this to determine whether to render a barcode in your UI.
      </td>
    </tr>

    <tr>
      <td>
        hasStockInfo
      </td>

      <td>
        Boolean
      </td>

      <td>
        Specifies whether the offer includes stock information. If true, the stockInfo field will be populated with available denominations.
      </td>
    </tr>

    <tr>
      <td>
        offerRates
      </td>

      <td>
        \[OfferRate]
      </td>

      <td>
        Represents the specific reward rates and conditions associated with an offer.
      </td>
    </tr>

    <tr>
      <td>
        denominationsType
      </td>

      <td>
        OfferDenominationType
      </td>

      <td>
        Defines the type of denominations available for the offer. This field is used to specify how the offer's value is structured, such as fixed or variable denominations.
      </td>
    </tr>

    <tr>
      <td>
        termsAndConditions
      </td>

      <td>
        String
      </td>

      <td>
        The terms and conditions text for this offer (legal language, restrictions, expiration policies). Use this to surface T\&C to end users before they purchase a gift card.
      </td>
    </tr>

    <tr>
      <td>
        stockInfo
      </td>

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

      <td>
        StockInfo is a list of available denominations for a specific offer. It's only available if the offer hasStockInfo. This requires Fluz to confirm the inventory, response time varies by vendors. The stockInfo field will conditionally return info depending on the  `VARIABLE` or `FIXED` type. To query for stockInfo, you will need to utilize an inline fragment using the `... on`keyword. This will return `StockInfoVariableType` if the denomination type is `VARIABLE` or `StockInfoFixedType` if the denomination type is `FIXED`.

        For more detail, refer to the [How the GraphQL API works](/concepts/graphql)  article.
      </td>
    </tr>
  </tbody>
</Table>

### Understanding the 'Offer rate':

The `OfferRate` object represents the specific reward rates and conditions associated with an offer. This object contains detailed information about the rewards that users can receive when they take advantage of an offer, as well as the conditions under which these rewards apply:

| Field Name                 | Type      | Description                                                                                                                                                                                                                      |
| :------------------------- | :-------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| maxUserRewardValue         | Float     | The maximum value cashback that a user can receive. This field defines the upper limit of the reward amount that a user can earn for a specific offer.                                                                           |
| cashbackVoucherRewardValue | Float     | The cashback value after a boost is applied to the offer. Typically this is a 25% cashback boost on the first \$10 of your spend.                                                                                                |
| boostRewardValue           | Float     | When the cashback value is increased on an offer, it will display here. These offers are an additional incentive that may be offered to users for a period of time.                                                              |
| displayBoostReward         | Boolean   | Indicates whether the boost reward should be displayed to the user. This field is used to control the visibility of the boost reward in the user interface.                                                                      |
| denominations              | \[String] | An array of denominations that are eligible for the offer. These denominations represent specific amounts (e.g., "10", "25", "50") that are applicable for the offer, defining the monetary values that qualify for the rewards. |
| allowedPaymentMethods      | \[String] | An array of payment methods that are allowed for this offer. This field specifies which payment methods (e.g., "CREDIT\_CARD", "PAYPAL") can be used by the user to take advantage of the offer.                                 |

<br />

<StickyContactSalesBanner />