Get Merchant Catalog

getMerchants

To get Fluz's current merchant catalog, you'll need LIST_OFFERS scope. Use the getMerchants query to get our current list of available merchants and their offers. This query can also take a merchant name or pagination as optional input arguments if you would like to refine the response.

📘
Retrieving our entire merchant catalog can be a time consuming and unnecessary step. We recommend only running the full query once per day. If you need to get specific merchant information, you can filter the 'getMerchants' query by the optional 'name' input to get a more refined response.

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

Sample request:

query getMerchants(
  $name: String,
  $paginate: OffsetInput
) {
  getMerchants(
    name: $name,
    paginate: $paginate
  ) {
    merchantId
    name
    slug
    offers {
      offerId
      stockInfo {
      ... on StockInfoVariableType {
        __typename
        description
        maxDenomination
        minDenomination
      }
      ... on StockInfoFixedType {
        __typename
        denomination
        availableStock
      }
    }
    }
  }
}

Sample Response:

Here's an example response you will get from the getMerchants query:

{
  "data": {
    "getMerchants": [
      {
        "merchantId": "123e4567-e89b-12d3-a456-426614174000",
        "name": "Best Buy",
        "slug": "best-buy",
        "offers": [
          {
            "offeringMerchantId": "255f8245-02c7-4817-901e-15fe265f6968",
            "offerId": "1a2b3c4d-5e6f-7g8h-9i10-jk11l12m13n14",
            "type": "GIFT_CARD_OFFER",
            "hasStockInfo": true,
            "offerRates": [
              {
                "maxUserRewardValue": 50.0,
                "cashbackVoucherRewardValue": 5.0,
                "boostRewardValue": 10.0,
                "displayBoostReward": true,
                "denominations": ["10", "500"],
                "allowedPaymentMethods": ["CREDIT_CARD", "DEBIT_CARD"]
              }
            ],
            "denominationsType": "FIXED",
            "stockInfo": 
              [
                {
                  "__typename": "StockInfoFixedType",
                  "denomination": 500,
                  "availableStock": 200
                }
              ]
           }
          }
        ]
      },
      {
        "merchantId": "223e4567-e89b-12d3-a456-426614174001",
        "name": "H&M",
        "slug": "h&m",
        "offers": [
          {
            "offeringMerchantId": "3c7b4d5e-6f7g-8h9i-10jk-11l12m13n14o",
            "offerId": "2a2b3c4d-5e6f-7g8h-9i10-jk11l12m13n15",
            "type": "EXCLUSIVE_RATE_OFFER",
            "hasStockInfo": false,
            "offerRates": [
              {
                "maxUserRewardValue": 30.0,
                "cashbackVoucherRewardValue": 3.0,
                "boostRewardValue": 8.0,
                "displayBoostReward": false,
                "denominations": ["20", "50", "100"],
                "allowedPaymentMethods": ["CREDIT_CARD", "PAYPAL"]
              }
            ],
            "denominationsType": "FIXED",
            "stockInfo": []
          }
        ]
      }
    ]
  }
}

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

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:

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.
hasStockInfo	Boolean	Specifies whether the offer includes stock information. If true, the stockInfo field will be populated with available denominations.
offerRates	[OfferRate]	Represents the specific reward rates and conditions associated with an offer.
denominationsType	OfferDenominationType	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.
stockInfo	[StockInfoType]!	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 Using Fragments with Unions and Interfaces article.

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.

Updated 2 days ago