Gift Card Offers

Scope Required: LIST_OFFERS (API Reference Link)

This page details how to retrieve and understand Gift Card Offers using the getMerchants query. Gift Card offers typically include types like GIFT_CARD_OFFER and EXCLUSIVE_RATE_OFFER.

To fetch only Gift Card offers, use the offerTypes input argument set to { giftCardOffer: true, cardLinkedOffer: false }.

Detailed Query for Gift Card Offers

This query requests fields specifically relevant to Gift Cards, including reward rates (offerRates) and stock availability (stockInfo).

Sample Request:

# Define the query with variables
query GetGiftCardMerchants(
  $name: String,
  $paginate: OffsetInput,
  $offerTypes: OfferTypesInput # Define the input type for offerTypes (optional)
) {
  getMerchants(
    name: $name,
    paginate: $paginate,
    offerTypes: $offerTypes # Pass the variable here (optional)
  ) {
    merchantId
    name
    slug
    offers {
      offerId
      type
      hasStockInfo
      denominationsType # FIXED or VARIABLE
      # --- Offer Rates (Relevant for Gift Cards) ---
      offerRates {
        maxUserRewardValue
        cashbackVoucherRewardValue
        boostRewardValue
        displayBoostReward
        denominations
        allowedPaymentMethods
      }
      # --- Stock Info (Relevant for Gift Cards) ---
      stockInfo {
        ... on StockInfoVariableType {
          __typename
          description
          maxDenomination
          minDenomination
        }
        ... on StockInfoFixedType {
          __typename
          denomination
          availableStock
        }
      }
      # --- CLO Details (Will be null for Gift Cards) ---
      # cloDetails { currentRateType } # Can query, but expect null
    }
  }
}

# Example Variables to pass with the query:
# {
#   "paginate": { "limit": 20, "offset": 0 },
#   "offerTypes": { "giftCardOffer": true, "cardLinkedOffer": false }
# }

Sample Response (When Filtering for Gift Card Offers):

The response will contain merchants, but the offers array for each merchant will only include offers matching the offerTypes filter (in this case, Gift Card Offers).

{
  "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": []
          }
        ]
      }
    ]
  }
}

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.

Want to learn more? Contact us at [email protected]

Speak with our experts for more info or to request a demo.