Get Merchant Catalog

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 }).

📘

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

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
) {
  getMerchants(
    paginate: $paginate,
    offerTypes: $offerTypes
  ) {
    # --- Common Merchant Fields ---
    merchantId
    name
    slug
    # --- Basic Offer Info (Common to all types) ---
    offers {
      offeringMerchantId
      offerId
      type # Crucial field to identify offer type
      # 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 }
# }

Sample Response Structure (Gift Card Example):

{
  "data": {
    "getMerchants": [
      {
        "merchantId": "123e4567-e89b-12d3-a456-426614174000",
        "name": "Example Merchant",
        "slug": "example-merchant",
        "offers": [
          {
            "offeringMerchantId": "3c7b4d5e-6f7g-8h9i-10jk-11l12m13n14o",
            "offerId": "1a2b3c4d-5e6f-7g8h-9i10-jk11l12m13n14",
            "type": "GIFT_CARD_OFFER"
            // 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:

Common Offer Fields (within offers array):

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

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.