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

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 relevant to Gift Cards, are typically null or empty for CLOs and can often be omitted from the CLO query.

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 a sample response you will receive from the getMerchants query fetching only CLOs:

{
  "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 CLO. Returns null for non-CLO types. See the tables below for a breakdown of this object's fields.
  • offerRates: Typically null for CLOs. The rate information is contained within cloDetails.
  • stockInfo: Typically empty for CLOs since they are usually linked to card usage rather than pre-defined stock.
  • hasStockInfo: Usually false for CLOs.
  • denominationsType: Often VARIABLE for CLOs since 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 (CLOs).

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, SINGLE_DAY, WEEKLY, MONTHLY).
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.

Updated 1 day ago