> ## 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 }`).
* `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
# --- 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",
"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. |
| 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. |
## 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**](/get-gift-card-offers) 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**](/features/card-linked-offers) subpage for a detailed explanation and query examples.