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

getMerchants

Use the `getMerchants` GraphQL query to retrieve the current list of available merchants and their offers from the Fluz catalog. This is the primary way to discover which merchants are available and what kinds of deals they offer.

You can refine the results using optional input arguments:

* `name`: Filter merchants by a specific name.
* `paginate`: Control the number of results per page (`limit`) and the starting point (`offset`).
* `offerTypes`: Specify whether you want `giftCardOffer`s, `cardLinkedOffer`s, or both using boolean flags (e.g., `{ giftCardOffer: true, cardLinkedOffer: false }`).
* `categoryId`: Return only merchants in one shopping category, for example Dining or Travel. Category ids come from [`getMerchantCategories`](https://docs.fluz.app/api-reference/queries/get-merchant-categories). An unknown or inactive category returns an empty list.
* `filterBy`: An object used to apply specific filters to the offers within each merchant. If a merchant has no offers remaining after filtering, it is excluded from the final results.\
  Available filters:
  1. `deliveryFormat`: Filters gift card offers by their delivery method.\
     Allowed values: `URL`, `CODES`, `PIN_AS_CODE`, `PIN_WITH_URL`.

> 📘 Retrieving the entire merchant catalog without filters can be time-consuming. We recommend fetching the full, unfiltered catalog only once per day. For more frequent updates or specific lookups, use the `name` or `offerTypes` filters.

> 📘 **Notes on pagination:**
>
> The default and max limit for pagination is 20. The result will not necessarily return the amount that you define as the limit. For example, you may request a limit of 10, but the response may only have 7 results.
>
> When an offset is included, remember to include the limit amount in your offset calculation for the next batch. If no limit is specified, you will need to offset by the default limit of 20 (e.g. offset+20).

> 📘 **Fetching the full merchant catalog:**
>
> **If you want all available merchants, you must paginate until the API returns an empty array.**
>
> Steps to fetch the full catalog:
>
> 1. Call getMerchants (offset = 0, limit = 20).
> 2. Append the returned merchants to your local list.
> 3. Increase the offset by your limit (offset += 20).
> 4. Repeat the request.
> 5. Stop only when the API returns an empty array (\[]).

## Basic query structure

Here’s a flexible query structure using variables. You can adjust the `offerTypes` variable to fetch the specific offers you need. This example requests only the most common, basic fields.

**Sample request:**

```graphql theme={null}
# Define the query with variables
query GetMerchantCatalogBasic(
  $paginate: OffsetInput,
  $offerTypes: OfferTypesInput,  # Controls which offer types are returned
  $filterBy: FilterByInput
) {
  getMerchants(
    paginate: $paginate,
    offerTypes: $offerTypes,
    filterBy: $filterBy
  ) {
    # --- Common Merchant Fields ---
    merchantId
    name
    slug
    logoUrl        # Merchant logo image URL
    faceplateUrl   # Rectangular card art/faceplate image URL

    # --- Shopping categories (a merchant can be in more than one) ---
    categories {
      categoryId
      name
    }

    # --- Basic Offer Info (Common to all types) ---
    offers {
      offeringMerchantId
      offerId
      type          # Crucial field to identify offer type
      barcodeType   # Barcode format (NONE, C128, PDF417, QRCODE)
      # Request offer-specific fields like offerRates, stockInfo,
      # or cloDetails here based on expected types.
      # See subpages for details.
    }
  }
}

# Example Variables (Fetch Gift Cards Only):
# {
#   "paginate": { "limit": 20, "offset": 0 },
#   "offerTypes": { "giftCardOffer": true, "cardLinkedOffer": false }
# }

# Example Variables (Fetch CLOs Only):
# {
#   "paginate": { "limit": 20, "offset": 0 },
#   "offerTypes": { "giftCardOffer": false, "cardLinkedOffer": true }
# }

# Example Variables (Filter by deliveryFormat: CODES):
# {
#   "paginate": { "limit": 20, "offset": 0 },
#   "filterBy": { "deliveryFormat": URL }
# }
```

**Sample response structure (gift card example):**

```json json theme={null}
{
  "data": {
    "getMerchants": [
      {
        "merchantId": "123e4567-e89b-12d3-a456-426614174000",
        "name": "Example Merchant",
        "slug": "example-merchant",
        "logoUrl": "https://storage.googleapis.com/.../example-merchant-logo.jpg",
        "faceplateUrl": "https://storage.googleapis.com/.../example-merchant-faceplate.png",
        "categories": [
          { "categoryId": "223e4567-e89b-12d3-a456-426614174001", "name": "Dining" }
        ],
        "offers": [
          {
            "offeringMerchantId": "3c7b4d5e-6f7g-8h9i-10jk-11l12m13n14o",
            "offerId": "1a2b3c4d-5e6f-7g8h-9i10-jk11l12m13n14",
            "type": "GIFT_CARD_OFFER",
            "barcodeType": "C128"
            // Other fields like offerRates, stockInfo would be here
            // if requested and applicable.
          }
        ]
      }
    ]
  }
}
```

## Response details

The `Merchant` object returned by the `getMerchants` query includes the following fields:

| Field name | Type | Description |
| :- | :- | :- |
| merchantId | UUID! | The unique identifier for the merchant. This ID is essential for referencing the merchant in other API queries or transactions. |
| name | String | The name of the merchant. This is the display name that users will recognize when selecting a merchant for gift card usage or virtual card charges. |
| slug | String | A URL-friendly version of the merchant's name. The slug is often used in web addresses or as a reference in the user interface for ease of use. |
| logoUrl | String | The URL of the merchant's logo image. Typically a square (1:1) image suitable for display in merchant lists and headers. Returns null if not available. |
| faceplateUrl | String | The URL of the merchant's rectangular faceplate/card art image. This is ideal for displaying when no barcode is present (barcodeType === "NONE") or as a card background. Returns null if not available. |
| categories | \[MerchantCategory!]! | The shopping categories this merchant belongs to, ordered by display priority. A merchant can belong to more than one, and the list is empty when the merchant is uncategorized. Each entry has a `categoryId` and a `name`. |
| offers | \[Offer] | An array of `Offer` objects that represent the promotions, discounts, or deals available at the merchant. Each Offer object provides additional details such as the discount amount, expiration date, and any applicable conditions. |

Common Offer Fields (within offers array):

These fields are present in every `Offer` object, regardless of its type.

| Field Name | Type | Description |
| :- | :- | :- |
| offeringMerchantId | UUID! | A unique identifier for the merchant offering the specific deal or discount. This is a required field and must be a valid UUID. |
| offerId | UUID! | A unique identifier for the offer itself. |
| type | String! | Indicates the type of the offer. This could be a standard gift card offer or an exclusive rate offer. |
| deliveryFormat | DeliveryFormatType | Specifies the method by which the offer will be delivered to the user. This determines how the user will receive and redeem the offer. For card-linked offers, this field will be null as the offer is automatically applied. |
| barcodeType | BarcodeTypeEnum | Specifies the barcode format used for this offer. Possible values: NONE (no barcode), C128 (Code 128), PDF417, QRCODE. Use this to determine whether to render a barcode or display alternative visuals like faceplateUrl. |

## Filter by category

Merchants are grouped into the same shopping categories used in the Fluz catalog, such as Dining, Travel, and Grocery. Call [`getMerchantCategories`](https://docs.fluz.app/api-reference/queries/get-merchant-categories) once to get the list, then pass a `categoryId` to `getMerchants` to show one category at a time.

```graphql theme={null}
query GetMerchantCategories {
  getMerchantCategories {
    categoryId
    name
  }
}
```

```graphql theme={null}
query GetMerchantsByCategory($categoryId: UUID, $paginate: OffsetInput) {
  getMerchants(categoryId: $categoryId, paginate: $paginate) {
    merchantId
    name
    slug
    categories {
      categoryId
      name
    }
  }
}

# Example Variables:
# {
#   "categoryId": "223e4567-e89b-12d3-a456-426614174001",
#   "paginate": { "limit": 20, "offset": 0 }
# }
```

Notes:

* `categoryId` combines with the other arguments, so you can filter by category and `name` in the same call.
* A `categoryId` that isn't a UUID returns `APPLICATIONS-0012` (`InvalidArgument`) with the message `categoryId must be a UUID. Category ids come from getMerchantCategories.` A blank string is the exception: it removes only the category filter — `name`, `offerTypes`, `filterBy` and pagination still apply.
* Store the `categoryId` rather than the name if you cache the mapping — ids are stable, and a category can be renamed.
* Category assignments in the sandbox are test data and won't match production.
* The same pagination rules apply to a filtered call as to an unfiltered one.

## Offer type specific details

The real details of an offer depend on its `type`. You need to request and interpret different fields based on the offer type:

* **For gift card offers (`GIFT_CARD_OFFER`, `EXCLUSIVE_RATE_OFFER`):**
  * Key fields include `offerRates`, `stockInfo`, `hasStockInfo`, `denominationsType`, `allowedPaymentMethods`.
  * See the [**Gift Card Offers**](https://docs.fluz.app/get-gift-card-offers.md) subpage for a detailed explanation and query examples.
* **For card linked offers (`CARD_LINKED_OFFER`):**
  * The primary field is `cloDetails`, which contains rates, periods, and conditions.
  * See the [**Card Linked Offers**](https://docs.fluz.app/features/card-linked-offers.md) subpage for a detailed explanation and query examples.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.