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 giftCardOffers, cardLinkedOffers, 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:

Call getMerchants (offset = 0, limit = 20).

Append the returned merchants to your local list.

Increase the offset by your limit (offset += 20).

Repeat the request.

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:

# 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

{
  "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 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 subpage for a detailed explanation and query examples.

​Basic query structure

​Response details

​Offer type specific details

Basic query structure

Response details

Offer type specific details