Fluz API Overview
API ReferenceFluz
Start typing to search…

Card Linked Offers

Scope Required: LIST_OFFERS (API Reference Link)

This page details how to retrieve and understand Card Linked Offers (CLOs) using the getMerchants query. CLOs are identified by the type field value CARD_LINKED_OFFER and are often tied to usage of the Fluz Virtual Card. They use a distinct structure, cloDetails, for their rate and condition information, differing significantly from standard Gift Card offers.

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

Use the getMerchants query to retrieve merchants and their associated Card Linked Offers (CLOs). CLOs are special offers, often redeemable exclusively via the Fluz Virtual Card. Using the offerTypes input argument, you can specifically request only CLOs by setting cardLinkedOffer: true and giftCardOffer: false.

Detailed Query for Card Linked Offers

This query requests fields specifically relevant to CLOs, focusing on the cloDetails object. Fields like offerRates and stockInfo, which are pertinent to Gift Cards, are typically null or empty for CLOs and can often be omitted from the query for CLOs.

query GetCLOMerchants(
  $name: String,
  $paginate: OffsetInput,
  $offerTypes: OfferTypesInput
) {
  getMerchants(
    name: $name,
    paginate: $paginate,
    offerTypes: $offerTypes
  ) {
    merchantId
    name
    slug
    offers {
      offerId
      type # Will be CARD_LINKED_OFFER
      hasStockInfo # Usually false for CLOs
      denominationsType # Often VARIABLE for CLOs
      # --- Offer Rates (Usually null/empty for CLOs) ---
      # offerRates { maxUserRewardValue } # Can query, but expect null
      # --- Stock Info (Usually null/empty for CLOs) ---
      # stockInfo { ... on StockInfoVariableType { __typename } } # Usually empty
      # --- CLO Details (Relevant for CLOs) ---
      cloDetails {
        currentRateType
        regularRate
        promoRate
        promoBaseRate
        promoMaxCap
        applyPromoBaseRateAfterCap
        minimumPurchaseAmount
        activePeriodStartDate
        activePeriodEndDate
        periods {
          id
          offerRateType
          periodType
          startDate
          endDate
          startTime
          endTime
          daysOfWeek
          daysOfMonth
        }
      }
    }
  }
}

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

Sample Response:

Here's an example response you will get from the getMerchants query with CLO Offers Only:

{
  "data": {
    "getMerchants": [
      {
        "merchantId": "4b4195cb-ba98-49e6-8935-761458a76cdd",
        "name": "REI",
        "slug": "REI",
        "offers": [
          {
            "offeringMerchantId": "4b4195cb-ba98-49e6-8935-761458a76cdd",
            "offerId": "3edd79b7-aa46-4bd6-96de-b78e4f3a79e0",
            "type": "CARD_LINKED_OFFER",
            "hasStockInfo": false,
            "denominationsType": "VARIABLE",
            "stockInfo": [],
            "offerRates": null,
            "cloDetails": {
              "currentRateType": "PROMO",
              "regularRate": 22,
              "promoRate": 25,
              "promoBaseRate": 20,
              "promoMaxCap": 1523,
              "applyPromoBaseRateAfterCap": false,
              "minimumPurchaseAmount": null,
              "activePeriodStartDate": null,
              "activePeriodEndDate": null,
              "periods": [
                {
                  "id": "0cb1fde3-cfb5-4f31-b75f-eedf55d65ca7",
                  "offerRateType": "PROMO",
                  "periodType": "ALWAYS_AVAILABLE",
                  "startDate": null,
                  "endDate": null,
                  "startTime": null,
                  "endTime": null,
                  "daysOfWeek": null,
                  "daysOfMonth": null
                },
                {
                  "id": "21f57686-4139-4392-8eca-00cffad24fa1",
                  "offerRateType": "REGULAR",
                  "periodType": "ALWAYS_AVAILABLE",
                  "startDate": null,
                  "endDate": null,
                  "startTime": null,
                  "endTime": null,
                  "daysOfWeek": null,
                  "daysOfMonth": null
                }
              ]
            }
          },
          {
            "offeringMerchantId": "4b4195cb-ba98-49e6-8935-761458a76cdd",
            "offerId": "7ec04538-ad28-4d49-8181-f4ec108facc1",
            "type": "CARD_LINKED_OFFER",
            "hasStockInfo": false,
            "denominationsType": "VARIABLE",
            "stockInfo": [],
            "offerRates": null,
            "cloDetails": {
              "currentRateType": "PROMO",
              "regularRate": 4,
              "promoRate": 17,
              "promoBaseRate": 12,
              "promoMaxCap": 1999,
              "applyPromoBaseRateAfterCap": false,
              "minimumPurchaseAmount": null,
              "activePeriodStartDate": "2025-04-21",
              "activePeriodEndDate": "2025-04-27",
              "periods": [
                {
                  "id": "9f887399-7bd6-44ad-af04-3fccdafeb092",
                  "offerRateType": "PROMO",
                  "periodType": "MULTIPLE_DAYS",
                  "startDate": "2025-04-21",
                  "endDate": "2025-04-27",
                  "startTime": null,
                  "endTime": null,
                  "daysOfWeek": null,
                  "daysOfMonth": null
                },
                {
                  "id": "3769f838-f0a8-4971-9415-6bb15eae64be",
                  "offerRateType": "REGULAR",
                  "periodType": "ALWAYS_AVAILABLE",
                  "startDate": null,
                  "endDate": null,
                  "startTime": null,
                  "endTime": null,
                  "daysOfWeek": null,
                  "daysOfMonth": null
                }
              ]
            }
          }
        ]
      }
    ]
  }
}

Card Linked Offer Specific Fields Explained

When offer.type is CARD_LINKED_OFFER, the primary source of information is the cloDetails object within the Offer.

  • type (String!): Will always be CARD_LINKED_OFFER.
  • cloDetails (CloDetails): This complex object contains all the specific rate, promotion, timing rules, and conditions for the Card Linked Offer. Returns null for non-CLO types. See the tables below for a breakdown of its fields.
  • offerRates: Typically null or empty for CLOs. The rate information is contained within cloDetails.
  • stockInfo: Typically empty for CLOs as they are usually linked to card usage rather than pre-defined stock.
  • hasStockInfo: Usually false for CLOs.
  • denominationsType: Often VARIABLE for CLOs, reflecting that the offer applies to a transaction value rather than a fixed gift card amount.

Understanding the CloDetails Object

This object provides the specific rate structure for Card Linked Offers.

Field NameTypeDescription
currentRateTypeCloRateTypeEnum!Indicates if the REGULAR or PROMO rate is currently active, determined by evaluating all periods against the current time. (REGULAR, PROMO)
regularRateFloatThe standard reward rate applied when no promotion is active.
promoRateFloatThe promotional reward rate applied when a PROMO period is active and the purchase amount is below or equal to promoMaxCap (if applicable).
promoBaseRateFloatThe reward rate applied during a PROMO period after the promoMaxCap has been exceeded, if applyPromoBaseRateAfterCap is true.
promoMaxCapFloatThe maximum purchase amount (currency value) up to which the promoRate applies during a PROMO period. Purchases above this amount may earn promoBaseRate or the regularRate, depending on flags.
applyPromoBaseRateAfterCapBooleanIf true, the promoBaseRate is applied to the portion of the purchase amount exceeding the promoMaxCap during an active PROMO period. If false, amounts over the cap might earn no reward or the regularRate.
minimumPurchaseAmountFloatThe minimum transaction value required to qualify for any reward from this CLO, if specified.
activePeriodStartDateStringThe start date (YYYY-MM-DD) of the currently active offer period (could be regular or promo), if the active period has defined start/end dates. null if always active or based on other criteria.
activePeriodEndDateStringThe end date (YYYY-MM-DD) of the currently active offer period, if applicable. null if always active or open-ended.
periods[CloPeriod!]!A list of all defined time periods associated with this offer. The system evaluates these periods to determine the currentRateType. See the CloPeriod table below.

Understanding the CloPeriod Object (within CloDetails.periods)

Each object in the periods array defines a specific time window and the rate type (REGULAR or PROMO) associated with it. The combination of these periods determines the offer's availability and active rate.

Field NameTypeDescription
idUUID!Unique identifier for this specific period definition.
offerRateTypeCloRateTypeEnum!Indicates if this period corresponds to the REGULAR or PROMO rate structure defined in the parent CloDetails.
periodTypeStringDescribes the nature of the period's timing (e.g., ALWAYS_AVAILABLE, MULTIPLE_DAYS, SPECIFIC_DAY, RECURRING_WEEKLY).
startDateStringStart date (YYYY-MM-DD) when this period rule becomes potentially active.
endDateStringEnd date (YYYY-MM-DD) when this period rule ceases to be active.
startTimeStringStart time (e.g., "HH:MM" in UTC or a defined timezone) for daily applicability, often used with daysOfWeek.
endTimeStringEnd time (e.g., "HH:MM" in UTC or a defined timezone) for daily applicability.
daysOfWeek[String]Array of days (e.g., ["MONDAY", "FRIDAY"]) when this period rule is active. Used for weekly recurring periods.
daysOfMonth[String]Array of specific days of the month (e.g., ["1", "15"]) when this period rule is active. Used for monthly recurring periods.

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

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

Updated about 4 hours ago