Skip to main content

Data Integration

Purpose of this document​

This document provides details at the business, technical (including configuration), and implementation levels for specific features within the ES Loyalty feature set. It covers a subset of functionality focused on Data Integration.

Table of contents​

Console API suite​

The Console API suite contains the requests and responses that the Console uses to carry out its functions. These APIs are internal only and are not exposed to clients.

The calls are organized to mirror the Console menu structure:

  • Membership — Top-level functionality that lets an agent find a member using their loyalty ID, email address, or account associations. Once a member is found and selected, the agent can manage their details, including profile, extended data, cards and card status, point transfers, householding, discretionary points, badges, banners, and transactions.
  • Promotions — Includes Offers, Banners, Badges, and Campaign Management (including Campaigns, Seed Lists, and Offer Pool to manage Boost campaigns).
  • Analytics — Search functions for Standard and Custom Reports.
  • User Management — Manages Users, Groups, and Roles. Users belong to Groups, and Roles are applied to Groups to set permissions for various features.
  • Program Management — Manages Activity Types, Report Management (administration), Member Tiers Program, Expiry, Reporting Identifiers, Budget Management, Reward Identifiers, Ad Hoc Rewards, Redemption Catalogue, and Redemption Identifiers.

The Console API suite powers the Console, giving marketers, agents, and other client staff access to Exchange Solutions functionality through a user-friendly interface.

Gen AI API suite​

The Gen AI API suite is an internal set of APIs that serves as an interface between ES Loyalty features and ESI's GenAI module.

The Gen AI suite supports generative AI functions such as Gen AI Help (searching help content for Console users using their prompts) and the Audience Recommender (generating audiences from user prompts). The API currently supports requests to:

  • Determine prompt completion status
  • Save user feedback
  • Get and update system prompts

Fraud Plus API suite​

The Fraud Plus API suite is an internal set of APIs that serves as an interface between ES Loyalty features and the Fraud Plus module.

A fraud prevention feature covers several functional areas:

  1. Detection — Identifies unusual or suspicious activity within the loyalty program, using data points such as spending habits, location data, or transaction history.
  2. Analysis — Analyses flagged transactions or behavior to determine whether fraud has occurred, cross-checking against other data sources to validate legitimacy.
  3. Notification — Sends a notification to the appropriate team or individual when fraudulent behavior is detected — for example, an internal fraud prevention team, law enforcement, or the affected loyalty program member.
  4. Prevention — Takes steps to prevent future fraud, such as implementing additional security measures, educating members about security best practices, or updating internal policies.

Fraud Plus detects potentially fraudulent, erroneous, or excessive behavior, and provides information and advice to users and other systems on how to respond. The module is architected outside of the core ES Loyalty technical stack, which means it can be enhanced over time to add additional metrics, actions, and reporting, and can potentially serve other systems through its APIs.

To accomplish this:

  • Member-level, time-bound thresholds are configured — for example, more than 3 profile changes in a single day, or member-to-member points transfers exceeding 20,000 in a given week.
  • Fraud Plus "advice" is returned when these rules are triggered — for example, log only, or log and block redemption for 15 days.

When ES Loyalty (or another system) calls the Fraud Plus module, it returns any advice for a given member. In the current version, this applies in two ES Loyalty contexts:

  1. During the POS flow, the system calls Fraud Plus to check for any rules that prevent earn or burn.
  2. Within the Console member section, the system displays any flagged behavior for a given member.

The Fraud Plus module delivers information to the loyalty program administrator through emailed notifications and to agents through the Flagged Behavior section on a member's page (if enabled and if there is advice about a potentially fraudulent situation to display).

Data Integration Gateway (DIG) API suite​

The Data Integration Gateway (DIG) API suite is an internal set of APIs that serves as an interface between ES Loyalty features and external marketing systems.

The DIG is a generic module that accepts messages sent by ES Loyalty for various supported integrations. The module applies filtering rules to incoming messages and routes them to the appropriate connector module, which then consumes the message and interacts with an external vendor or provider — for example, a client's Email Service Provider, Data Integration Provider, or a specific API.

The DIG is implemented as an independent component with the following sub-modules:

  1. DIG API module — Consists of the API gateway, AWS Lambda, and EventBus. This module exposes a REST API interface that ES Loyalty uses to exchange data with the integrated provider. The API contains routing logic for synchronous, asynchronous, and batch file flows.
  2. Connector modules — Consist of Lambda and EventBus rules and contain the logic for connecting to specific integrated software.
  3. Database module — Creates the tables required for storing configuration and message data for auditing.

DIG API suite configuration determines which message types are supported and the filtering rules for messages.

Customer Experience API suite​

Use the Customer Experience API (CUX API) to give members — for example, on a website or in an app — the functionality they need to manage their membership and offers.

The REST CUX API includes requests and responses to:

  • Start user sessions
  • Handle member enrollment, opt-in, and profile updates
  • Handle balance and membership tier inquiries
  • Support offer, banner, and badge operations
  • Provide access to a member's transaction history
  • Support card operations such as validating, replacing, and managing loyalty card data
  • Send member activities to the system
  • Link a business unit to a member account

Start session​

The Start Session request begins an API session and establishes the identifiers used to associate subsequent requests with a member account.

Start Session begins a session with a customer account through a channel such as a website or mobile app. A session is required for any API interaction outside of enrollment. The request requires a unique identifier — the loyalty identifier, account ID, or external ID (client identifier) — which points to the account for which the session is opened. The request also requires a correlation ID and the channel (for example, an app, store, website, POS system, or partner).

The response includes the following information about the member:

  • The unique identifier used (account, loyalty, or external ID)
  • The membership type (regular or employee)
  • The user/account status (for example, active, unregistered, deceased, expired, closed, or cancelled)
  • The card status (for example, active, invalid, suspended, lost or stolen, damaged, fraud/abuse, cancelled, expired, or non-loyalty)
  • The card type (digital or physical)
  • Flags indicating whether the account is expired or suspended
  • Point and dollar balances, including points available for redemption
  • Minimum and maximum redemption limits for the current session
  • Cumulative redemptions year-to-date, including adjustments
  • The correlation ID for the session
  • Tier information including tier details, the member's tier and unique identifier, the date range and expiry date for the tier, and additional tier data
  • Contributions toward the next tier, current spend, and the amount required to reach the next tier
  • The relevant business unit for the member
  • Household data related to the member
note

Profile information (date of birth, gender, name, business name, address, and email address) has been moved to a separate Member Profile request. See Member profile below.

Additional information​

Member profile​

This API retrieves member profile data independently of a Start Session call, giving clients more flexibility in retrieving member data and allowing Personally Identifiable Information (PII) to be better managed and protected.

Member profile attributes represent the collection of attributes relevant to a loyalty program member. Both B2B and B2C loyalty programs require the ability to track meaningful attributes, which can vary by client.

Profile attributes for a specific client might include date of birth, gender, name, related business name, address, and email address. For example:

{
  "dateOfBirth": "1975-03-29",
  "gender": "M",
  "firstName": "Derek",
  "lastName": "Shep",
  "email": "dereks@gmail.com",
  "businessName": "RXL",
  "phoneNumber": "xxx-xxx-xxxx",
  "street": "street",
  "street2": "street2",
  "suite": "suite",
  "city": "city",
  "provinceState": "provinceState",
  "postalZipCode": "M5C 2C5",
  "countryCode": "countryCode",
  "languagePreference": "EN",
  "registrationDetails": {
    "registrationChannel": "STORE",
    "registrationDate": "2022-07-18T11:20:44.933Z",
    "registrationDateEpoch": 1658143244933
  }
}

Additional information​

Member management​

Member Management is a group of CUX API requests used to manage members and accounts. The requests are:

  • Enroll User or Update User Profile — Enrolls a customer in the loyalty program or updates profile information for an existing member. The request includes possible PII, email address (required), street address, language preference, enrollment channel, a unique card name, any extended data, and account associations. The response includes the account ID, card number, card status (always ACTIVE on enrollment), and card type (PHYSICAL or DIGITAL).
  • Account EMD Query — Retrieves Extended Member Data for a specified account.
  • Update Profile with Extended Data — Updates an account's primary attributes and can add extendedData attributes for reporting and analytics. This call works for both Loyalty and Non-Loyalty accounts. If the profile already includes extended data and is being updated, all extendedData should be sent. If the EMD should not change, omit the extendedData object.
  • Balance Query — Returns all relevant account balance information, including main, points, dollar, available, and redeemable balances, and minimum and maximum redemption limits in both points and dollars.
  • Membership Tier Query — Returns all membership tier information for the account, including tier code, name, and rank; the next tier's ID, rank, and name; contributions information; and related business units.
  • Member Search — Searches for a member using EMD on the account — for example, by partner linkage.
  • Set Opt-in Status — Sets the opt-in status for member communications on a user account.
  • Account Suspension — Programmatically suspends an account or removes a suspension. The request includes an action code (SUSPEND or REMOVE) and a reason. The response confirms the result.
  • Close Account with Options — Closes an account with options to zero account balances and/or anonymize the member's data.

The system must be able to manage member information for enrollment, extended data, balance and tier inquiries, and account status. It must also be able to manage opt-in preferences and account suspension.

Additional information​

EMD​

The CUX API supports Extended Member Data (EMD) for clients who want to store additional information about members beyond the standard key-value attribute pairs.

Clients store member data that is not standard to loyalty programs. ES Loyalty accepts this data as EMD. Current uses for EMD include audience targeting, display in the member admin Console, and reporting.

EMD currently uses atomic updates. If a client has multiple sources of EMD, they may overwrite each other's data unless the data is merged into a single source before being sent to ES Loyalty.

Extended member data is submitted through the CUX API User Enrollment/Profile Update POST request and retrieved through the CUX API Extended Member Data GET call.

Account closure​

This feature lets a user close an account, zero out the point balance, and anonymize member data.

The API call closes an account with options to zero the account balance and anonymize the member's data (masking data in the database to protect PII and setting the Opt-In flag to false). The AccountStatus is set to CLOSED and the LoyaltyStatus to CANCELLED. The account can no longer earn or redeem rewards.

Member gameplay​

This feature lets the system view gameplay rewards earned by a member.

Many retailers incorporate gamification to encourage spend, shape customer behavior, and collect zero-party data about customer preferences. This request returns gameplay rewards earned by a specified member.

Each gameplay record in the response includes:

  • Game identifier
  • Offer code — the name of the related offer
  • Gameplay URL — the URL the member uses to access the game
  • Game type
  • Transaction ID — unique identifier for the qualifying transaction
  • Earned date — date and time the gameplay was earned

Member aggregation​

This feature exposes member-level aggregations configured within ES Loyalty — for example, Total Redeemed Points (calendar year), Total Eligible $ Spend (calendar year), and Total Points Earned (calendar year).

If a client migrates to ES Loyalty mid-year, the aggregate values must be updated to reflect transactions that occurred outside of ES Loyalty. Historical transaction feeds do not affect aggregations.

The feature covers a data aggregation system with the following key areas:

  1. Historical data and aggregates — Historical data migration feeds preload and calculate aggregates. Configuration allows flexibility for adding, overwriting, or appending values during import.
  2. Design considerations — Aggregates are an internal implementation detail. The feature handles incoming data, manages date ranges, and updates existing aggregates.
  3. Separate feed for aggregates — A dedicated feed manages aggregates, separate from membership tier feeds, to avoid overlaps or dependencies.
  4. Flexibility and future-proofing — Configuration supports separate CUX API and Console functionality. Naming conventions and configuration ensure scalability.
  5. Error handling and validation — The system accounts for configuration mismatches between account and member-level distinctions, and implements error logging and warnings.

The supported granularity for the member override feed includes: DAY, YEAR, QUARTER, MONTH, and others.

Card operations​

Card Operations is a group of CUX API requests used to manage member cards. The requests are:

  • Validate Card — Validates whether a card is eligible for enrollment. A card is valid if it is allocated but not linked to an account, or if it is linked to an unregistered account. A card is invalid if it is linked to a registered account. The response returns true or false.
  • Replace Existing Card — Replaces a known account card with a new digital card. The old card is invalidated and the new card receives ACTIVE status. The update status must be one of: DAMAGED, CANCELLED, or LOST_OR_STOLEN. The response provides the new card number and a confirmation message.
  • Change Card Status — Changes the current status of a card. The response confirms the success of the operation.
  • Manage CardLabel and ExtendedData — Adds or replaces the cardLabel and extendedData attributes on a card object. Both attributes are optional, but at least one must be included. Sending cardLabel as an empty string removes the attribute. Sending extendedData as an empty object replaces the current value with an empty object.
  • Promote Secondary Card to Primary — Promotes a secondary card to the primary card on the account. The previous primary card retains ACTIVE status. Cannot be used if the account status is CLOSED or DECEASED.
  • Add Multiple Active Cards to Account — Adds physical and/or digital cards to an account as active cards. Only one card type (digital or physical) can be added per request. The account has a card limit; exceeding it returns an error. The response lists cards that were successfully added and those that failed, along with failure details.

The system must be able to manage loyalty cards associated with member accounts.

Additional information​

Offer/banner/badge operations​

This group of CUX API requests supports getting information about offers, loading offers, and responding to offers. It also includes requests for banners and badges.

Offers

  • Get All Offers — Retrieves all targeted offers available to the user based on criteria set in the Console, which may include age, gender, extended member attributes, partner associations, badge eligibility, and member tier.
  • Get Future Offers — Returns offers with an effective date in the future for the current session user, based on the same criteria as Get All Offers.
  • Respond to Offer — Accepts or declines an offer on behalf of a loyalty member. Valid states are ACCEPTED, DECLINED, and UNACCEPTED.
  • Load All Offers — Loads all unaccepted offers that are currently active based on their display, start, and end dates. Accepts the same reply options as Respond to Offer.
  • Get Best Offer — Returns the most relevant offer for the current session.
  • Get Completed Offers — Returns completed offers, excluding mass offers.
  • Get Accepted Offers — Retrieves all accepted offers for the customer (typically for customer portals).
  • Get Expired Offers — Retrieves all expired offers for the customer (typically for customer portals).
  • Get Historical Offers — Retrieves the full offer history for the customer (typically for customer portals).
  • Get Mass Offers (logged in) — Returns mass offers configured for all members after the user logs in. Mass offers may use any activation method but cannot target personal data such as age, gender, or postal code. The response includes productTargeting data.
  • Get Mass Offers (not logged in) — Returns the same mass offers when the user is not logged in.

Banners

  • Get Banner Offers — Returns all banners available to the user based on province or state.

Badges

  • Get Member Badges — Returns all badges associated with the member.

Offer requests primarily focus on retrieving lists of offers of various types. The exceptions are Respond to Offer and Load All Offers, which also support offer management. The banner and badge calls return a list of items.

Additional information​

Send activity​

The Send Activity request passes information about a member activity that qualifies for rewards into the Exchange Solutions system. Activities include events such as responding to a survey, downloading an app, or logging into the app. The request also includes the channel (for example, store, POS system, or website).

The request is sent either with or without an activity identifier (activityId). If no activityId is provided, the system generates a GUID and uses it as the activityId in the response.

If applicable, the request must include the business unit relevant to the member and the activity. The request must also include an ISO 8601-formatted date and may include extended data with additional field names and values.

Additional information​

Transaction history​

Transaction History is a paginated API call that returns rich transactional data for the member associated with the current session. To retrieve the next page of data, pass in a transactionId — typically the last transactionId returned in the previous page call. You can also pass any transactionId to start from that point in the history; however, very old transaction IDs may return no results. There is no indicator of remaining data until you request a page that returns fewer items than the configured page size limit.

The request supports query parameters for filtering results, including to and from dates, a limit on the number of records returned, and a transactionId for starting from a specific transaction. The following transaction action types are supported:

  • ACCOUNT_EXPIRY — Points clawed back due to account-level expiry
  • ACTIVITY — Bonus points awarded for a reported activity event or behavioral offer
  • ADHOC_REWARD — Points awarded by a partner or business unit on an ad hoc basis
  • ADHOC_REDEMPTION — Points redeemed by a partner or business unit on an ad hoc basis
  • ADJUSTMENT — Points clawed back during an adjustment
  • ADJ_NO_RECEIPT — Points clawed back during an adjustment without an original transaction
  • DISCRETIONARY — Points awarded through discretionary processes such as goodwill
  • EXPIRY — Points clawed back during points expiry
  • FIFO — Points removed from account due to First-In First-Out expiry or auto-redemption
  • FINALIZE — Points awarded during a finalize transaction from the POS
  • MERGE — Points transferred during a merge request
  • POINTS_TRANSFER — Points transferred from one account to another
  • POST — Points posted to an account to correct the balance
  • PPE — Points awarded against an originally anonymous transaction (Post-Purchase Earn)
  • PURCHASE — Points awarded for a purchase transaction from a feed or any process that skips the trial/finalize/SAF flow
  • SAF — Points awarded during a SAF transaction from the POS
  • TRANSFER — Points transferred outside of a merge request (account to account with no victim account)
  • TRIAL — Used internally; Trial actions should never generate transactions to the database
  • UNKNOWN — Default transaction action type; if used, something has gone wrong
  • VOID — Points clawed back during a full adjustment; under normal circumstances this does not appear in history, but may appear for non-trivial transactions

Transaction parts may also have their own action types:

  • BASE — Base points earned
  • BONUS — Bonus points earned (excluding targeted offers)
  • DISCRETIONARY — Discretionary points awarded
  • EXPIRY — Points clawed back due to account expiry or FIFO expiry date
  • REDEEM — Points redeemed by the member or auto-redeemed at the FIFO auto-redemption date
  • TARGETED — Points earned for targeted offers
  • TRANSFER_IN — Points transferred from another account through merger or transfer
  • TRANSFER_OUT — Points transferred to another account through merger or transfer

Additional information​

Void transaction​

This feature voids a transaction within a configured number of days from the original transaction date. It also supports configuration of whether voided transactions appear in the member's transaction history. Supported transaction types include regular transactions and partner/business unit transactions such as ad hoc rewards and ad hoc redemptions.

Void transactions

Void transactions fully reverse previous transactions that awarded or redeemed points. For example, if a member redeemed points for a catalogue item and then returned it, the void mechanism returns the points to their account.

Housekeeping processes related to voids include adjusting the member's balance, recording the transactions correctly, and including or excluding them from the transaction history based on configuration.

Transaction history behavior

Previously, and as the current default, a void completely reversed the original transaction and removed both the original transaction and the void from the member's transaction history. A configuration flag now supports either removing both transactions or including both in the transaction history, depending on client preferences.

Related features include:

  • A feature switch to control whether the original ad hoc reward or redemption and the void transaction are included or excluded from the transaction history
  • Display of the void transaction in the Console with relevant details
  • Support for positive void amounts (rebate of rewards on reversal of a redemption) or negative void amounts (clawback of rewards on reversal of a reward)

Reporting

Reporting currently covers points rewarded or redeemed at the aggregate level. Void transactions cancel out the original transaction in reports.

Additional information​

Configuration​

The void feature flag is already part of the existing configuration. The adjustment feature in the CUX and Partner APIs has been enhanced with:

  • A check on whether the original transaction action is eligible for a void (must be ADHOC_REWARD or ADHOC_REDEMPTION)
  • A flag to verify that the partner for the original transaction matches the partner for the void transaction
  • A flag to include or exclude voided transactions (both the original and the void) from the transaction history — defaults to false

Post purchase earn​

This feature lets members perform post-purchase earn from the client website or mobile app without requiring an agent to update their points.

  • Applies the same rules as standard PPE
  • Assumes no direct PPE fraud control (the client can optionally control this through the front end)
  • Enhances the API to add channel data
  • Requires the member to have access to the transaction ID for the qualifying transaction

The following validations apply:

  • The account and loyalty ID must be eligible to earn
  • PPE must be performed within a configured number of days from the original transactionDate
  • The latest transaction in the original transaction chain must be anonymous

Additional criteria:

  • Invalid requests are rejected
  • Valid requests are processed correctly, including:
    • Incrementing the member's balance
    • Updating the last activity date (LAD) if earn is enabled as a tracking activity
    • Returning the household balance if the member is part of a household

Additional information​

FIFO​

FIFO (first in, first out) is an inventory management and accounting concept applied to loyalty. It means that the earliest points earned are the first to be redeemed or expired. Points that are not used within a certain duration are either expired (removed from the account) or auto-redeemed (converted to another form such as a voucher or loyalty card).

This feature has two components: (1) FIFO tracking of points, and (2) a process to sweep them to redemption or expiry. The Get Upcoming Point Sweep request returns a list of pending point sweeps for a specific account.

Each sweep is identified by month and indicates the number of points that will be swept on the last day of that month.

Additional information​

Business unit linking​

Business unit linking supports two requests:

  • Add/Update Business Unit Link — Adds or updates a business unit link. Multiple links can be added if they are attached to the user from the correlation_id.
  • List Business Unit Links — Lists all business unit links for the account.

For some business units, an external link is required to connect their users to the central loyalty program. To support call center scenarios where agents may not know whether a customer is already connected, clients can syndicate this information to ES Loyalty and view it in the Console.

Additional information​

Account associations​

This feature lets the system create associations between ES Loyalty accounts. The Account Association requests support creating, updating, deleting, and listing associations for a specified account:

  • Create Association — Creates an association for a specified account
  • Update Association — Updates association information for a specified account
  • Delete Association — Deletes an association from a specified account
  • Get All Associations of a Member — Lists all associations for a member account

Associations support reporting roll-ups (aggregated results for associated accounts) and let Console users be aware of associations so they can apply relevant business logic — for example, performing points transfers.

Each account can associate at two levels:

  1. Parent (Bill-to) — Defines an account's parent. An account can only associate with one Bill-to.
  2. Children (Ship-tos) — Defines an account's children. An account can associate with multiple Ship-tos, provided that each Ship-to is not already associated with a different Bill-to.

Associations can be configured through client applications or the ES Loyalty Console. An association can be made with any existing ES Loyalty account regardless of its status (including Cancelled or Unregistered). Either account can initiate or delete the association. There is currently no upper limit on the number of associations.

Additional information​

Partner program​

This feature links a financial partner's payment products to the loyalty program to accelerate program acquisition and increase earn and burn opportunities. Future capabilities may include:

  • Earning limits (for example, 2% worth of points, up to $500 value per month)
  • Earning rate tiers (for example, 2% back on the first $1,000 annual spend, 1% back beyond that)
  • Bonus points for related behaviors (for example, earn 10,000 bonus points when you link)
  • Variable earn rates by category (for example, 3% back on beauty, 2% on everything else)

The feature links a member's loyalty account to a partner's payment card so the member can earn additional points for activities related to using that card.

Additional information​

Member householding​

The householding feature lets multiple loyalty participants — whether personal, family, or business relations — coordinate their loyalty experience. Each member owns their own points and can independently join or leave a household. The Primary member has broader permissions than Secondary members, including the ability to view data for other household members. If the Primary member leaves the household, the household is deleted.

All household members contribute to a shared household point balance. Only members with household redemption privileges can redeem from this shared balance. When a redemption is made from the household balance, points are drawn proportionally from each member's redeemable balance.

For example:

  • Member A's balance: 100 points
  • Member B's balance: 200 points
  • Member C's balance: 0 points
  • Household redeemable balance: 300 points
  • Member C redeems 100 points — 67 points come from Member B's account, and 33 from Member A's (rounding applies)

Members without household redemption privileges can still redeem from their own personal balance.

Additional information​

Issuance​

This feature manages the issuance of rewards to loyalty program members. Currently, issuances are used for vouchers only.

The request supports a wide range of query parameters to filter results, including a maximum limit on the number of vouchers returned, a date range, a specific business unit, the issuance type (currently VOUCHER only), and the issuance status.

Additional information​

Ad hoc rewards​

This feature lets a client or their partners award member points in real time through an API request and response, with related reporting.

The ADHOC_REWARD API is used by client partners and business units to issue ad hoc bonus points to members without running a promotion in Exchange Solutions. Issuers associate rewards with a reward identifier for reporting purposes, which is maintained in the Console.

The API includes the channel (for example, APP, ONLINE, or STORE), a business unit, a unique member identifier, a unique session ID, unique identifiers for the issuer and the reward, and the reward amount. The response returns the transaction ID and a result message, or an error message if the call fails.

All points awarded through this method are bonus points. Receiving members are validated as active. Reward identifiers distinguish one bonus reward from another for the same issuer.

The reward amount can be positive or negative. It must be a whole integer and is subject to the maximum points per transaction limit set at the client or program level (not the partner level).

For reporting, ad hoc rewards roll up into bonus aggregations per user and can be further broken down by reward identifier.

Ad hoc rewards require two API calls:

  • Create Ad Hoc Reward ID — Used to issue ad hoc bonus points without running a promotion in ES Loyalty. Bonus points can also be awarded via regular feed processing or file upload through the Console. This request also handles negative rewardAmount values for FIFO points expiry.
  • Issue Ad Hoc Reward — Issues bonus points to a loyalty program member account in real time.

Additional information​

Ad hoc redemptions​

This feature lets a client or their partners redeem member points for in-store or catalogue items.

The client or partner must be able to perform real-time redemptions through the API and bulk redemptions through a batch process (both back-end and Console). Both feeds and APIs support reject handling based on the unique correlation ID. A processing summary response is available for bulk integrations for both the Console and SFTP.

The APIs retain the existing workflow to prevent negative balance scenarios: Inquiry > Reservation > Transaction > Finalize. Reservation does not apply to batch (feed) intake, but batch processing does not execute negative balance transactions.

Only business units and linked partners that have been enabled can redeem points. They are identified by a unique redeemer ID. Only pre-defined, enabled redemption IDs are eligible for ad hoc redemptions.

Examples of ad hoc redemptions (Redeemer ID | Redemption ID — description):

  • ClientA | Store_item_soda_123 — Redeem for item in-store or at station
  • ClientB | Catalogue_SafetyKit — Online catalogue redemption
  • ClientC | iTravel_Jan_2023 — Unofficial partner use case
  • ClientD | Investment_Consult — Hypothetical "Linked Partner" use case

Ad hoc redemptions require three API calls:

  • Reserve for Redemption
  • Issue Ad Hoc Redemption
  • Cancel Reservation

Additional information​

Point of Sale API suite​

Use the POS API for primarily transactional interactions, such as at retail point of sale or in online checkout experiences. The ES Loyalty POS API is optimized for high reliability and steady response times suitable for country-wide or global use in retail and e-commerce checkout solutions.

Start session (POS)​

The Start Session request begins an API session and establishes the identifiers used to associate subsequent requests with a member account.

Business requirements​

This request begins a session with a customer account through a POS system. A session is required for any API interaction outside of enrollment. The request requires a unique identifier — the loyalty identifier, account ID, or external ID — which points to the account for which the session is opened. The Start Session call also creates a correlation ID used as the session identifier.

Start Session provides two API call options:

  • Start Session on Behalf of Loyalty Account — Starts a new session for a specified loyalty account, captures a correlationId for all calls during the transaction, and returns account and card status, balance information, minimum and maximum redeemable values, and the appropriate prompt or receipt message.
  • Start Session without Loyalty ID — Initiates an anonymous session and captures a correlation ID for all calls during that customer session.

Additional information​

Prompt responses​

This feature sets options and details for a member through the POS terminal, including capturing an email address for a loyalty ID and setting the opt-in status.

Prompt responses involve two API calls:

  • Set Email Address for Loyalty ID — Captures an email address and associates it with a ghost card. The status parameter indicates the user's email prompt preference: deferred, accepted, or declined.
  • Set Opt-In Status for Loyalty ID — Captures opt-in status for loyalty program communications.

Additional information​

Redemption​

This feature lets a client or their partners redeem member points for in-store or catalogue items.

The client or partner must be able to perform real-time redemptions through the API and bulk redemptions through a batch process (both back-end and Console). Both feeds and APIs support reject handling based on the unique correlation ID.

The APIs retain the existing workflow to prevent negative balance scenarios: Inquiry > Reservation > Transaction > Finalize. Reservation does not apply to batch intake, but batch processing does not execute negative balance transactions.

Only business units and linked partners that have been enabled can redeem points. They are identified by a unique redeemer ID. Only pre-defined, enabled redemption IDs are eligible.

Examples (Redeemer ID | Redemption ID — description):

  • ClientA | Store_item_soda_123 — Redeem for item in-store or at station
  • ClientB | Catalogue_SafetyKit — Online catalogue redemption
  • ClientC | iTravel_Jan_2023 — Unofficial partner use case
  • ClientD | Investment_Consult — Hypothetical "Linked Partner" use case

Additional information​

Transactions​

The Transactions API supports all loyalty program behavior at the POS, including base point earning, bonus point earning, point redemption, customer and receipt messaging, and prompts. It also supports programmatic ingestion of POS transaction data on a regular cadence.

Trial Activity request — Sends the current purchase transaction to ES Loyalty to retrieve a point estimate. Works with the Near-Miss Prompt feature to advise customers at POS or in e-commerce about a bonus offer or earning threshold they are close to achieving.

Finalize request — Sends a finalize activity for a user and returns details about earning, redeeming, and offer rewards for the purchase transaction. When a valid reservation token is included, the system processes the redemption.

Store and Forward (SAF) request — Sends finalized transaction details where the data was stored and forwarded. If ES Loyalty and the client POS or e-commerce storefront lose connectivity, all finalized calls should be converted to SAF for forwarding later. SAF cannot process redemptions; these are processed once connectivity is restored. SAF transactions still qualify for rewards, but the transaction date is backdated to when the offers occurred to maintain reporting accuracy.

Transactions (behavior recognition):

Redemption:

Prompts:

Finalize​

The Finalize request finalizes an activity and returns the relevant details, including earning, redeeming, and offer rewards for the transaction.

This request sends a finalize activity for a user and returns details about earning, redeeming, and offer rewards for the purchase transaction. When a valid reservation token is included, the system processes the redemption.

In some cases, points can only be awarded after payment or fulfillment is complete, resulting in delayed transactions. Adding the confirmation object to the end of the call supports a delayed transaction that requires confirmation.

Additional information​

Store and forward (SAF)​

The SAF request sends finalized transaction details for a user where the data was stored and forwarded due to a connectivity interruption.

If ES Loyalty and the client POS or e-commerce storefront lose connectivity, all finalized calls should be converted to SAF for forwarding later. SAF cannot process redemptions; these are processed once connectivity is restored. SAF transactions still qualify for rewards, but the transaction date is backdated to when the offers occurred to maintain reporting accuracy.

If a purchase by a non-loyalty account is delayed being sent into the system until after the user registers, no points are awarded — the user was not associated with a loyalty account when the purchase was made.

In some cases, points can only be awarded after payment or fulfillment is complete, resulting in delayed transactions. Adding the confirmation object to the end of the call supports a delayed transaction that requires confirmation.

Additional information​

Trial​

The Trial request sends the current purchase transaction to ES Loyalty to retrieve a point estimate. It works with the Near-Miss Prompt feature to advise customers at POS or in e-commerce about a bonus offer or earning threshold they are close to achieving.

  • Sends a "non-finalized" activity (a transaction detail) for a user
  • Returns details about what the customer would have earned if this had been sent as a real activity
  • Returns the dollar difference between the amount spent and the amount that would have triggered a bonus offer or earning threshold, rounded to two decimal places
  • Optional: the callId can be included to further identify the request in reporting; if not provided, a GUID is generated

Additional information​

Post purchase earn (POS)​

This feature lets members complete post-purchase earn through a website or in-store. For example, if a member forgets to scan their loyalty card at a gas station, the printed receipt includes a barcode. The member can bring the receipt to the station attendant, who scans the barcode to award the loyalty points. Alternatively, the member can call the service desk and provide their transaction number for a Customer Service Agent (CSA) to award the points through the Member page.

Business requirements​

Members can only earn one form of loyalty per transaction. For transactions without a loyalty swipe at the pump or in-store, a barcode must be printed on the receipt so the member can present it in-store to append loyalty information to the original transaction.

One possible PPE workflow:

  1. The POS scans the barcode on the receipt to retrieve the original transaction and appends the loyalty information. ESI adds the loyalty information to the original transaction using the same loyalty sequence ID.
  2. A reconciliation is created for the loyalty settlement. Depending on the client's systems, this can take different forms — for example, sending a dummy transaction number with a loyalty reconciliation ID. A new receipt is produced at POS to show the loyalty information, marked as a revised version of the original.
  3. A time limit (for example, 7 days) may apply for how long the member has to claim their loyalty rewards.

Additional information​

Adjustment​

An adjustment (or partial reversal) removes some items from the original cart while leaving others, and claws back the corresponding points, program contributions, frequency offer contributions, and offer completions. Membership tier eligibility may also be adjusted.

Four API requests are available for adjustments, depending on the circumstances:

  • Adjust Points in a Basket (with Receipt) — Deducts loyalty points based on items returned from the cart within reversalLineItems. The correlationId for the original transaction is passed in the request path. Time restrictions on how old a transaction can be may apply.
  • No-Receipt Adjustment — Adjusts points when a transaction receipt is not available. No-Receipt Adjustments do not reference the original transaction, so original offers cannot be clawed back. Points are clawed back against Base and Base Membership offers (excluding frequency offers). Relevant program contributions are clawed back and membership tiers are adjusted where applicable.
  • Void a Transaction — Performs a full reversal, including reversing any points earned or redeemed. Neither the original transaction nor the void appear in the member's transaction history. A void can also reverse a redemption, returning the consumed points to the member's account.
  • Confirm Delayed Transaction — Provides confirmation details against a prior transaction that included a confirmation request. The mode parameter indicates the confirmation type (for example, CART = Full Cart Confirmation). Once the transaction is fully confirmed, ES Loyalty releases any points on hold from the original transaction, making them available on the account.

Additional information​

Partner Program API suite​

Use the Partner Programs API to power links between the primary loyalty program and external partners — for example, a banking partner that wants to link their credit cards to the loyalty program.

Search loyalty account​

The Search Loyalty Account request lets the system search programmatically for members with partner links, using either the account loyalty ID or the unique identifier for partner links.

Returns the loyalty account ID and link status based on an email address, loyaltyId, or partnerLinkIds. Up to 25 individual emails, loyalty IDs, or partner link IDs can be searched at once. The response returns results with or without account balances.

This feature lets an external client create one or more links to a single loyalty program for one or more accounts, and link to a financial partner's payment products to increase program acquisition and earn and burn opportunities. Future capabilities may include earning limits, earning rate tiers, bonus points for related behaviors, and variable earn rates by category.

The feature links a member's loyalty account to a partner's payment card so the member can earn additional points for activities related to using that card.

Additional information​

Issue ad hoc reward​

This feature lets a client or their partners award member points in real time through an API request and response, with related reporting.

The Issue Adhoc Reward API is used by client partners and business units to issue ad hoc bonus points to members without running a promotion in Exchange Solutions. Issuers associate rewards with a reward identifier for reporting purposes. A list of valid reward identifiers is maintained through the Console.

All points awarded through this method are bonus points. Receiving members are validated as active. The reward amount can be positive or negative, must be a whole integer, and is subject to the maximum points per transaction limit set at the client or program level.

Issue ad hoc redemption​

This feature lets a client or their partners redeem member points for in-store or catalogue items.

The client or partner must be able to perform real-time redemptions through the API and bulk redemptions through a batch process (both back-end and Console). Both feeds and APIs support reject handling based on the unique correlation ID.

The APIs retain the existing workflow to prevent negative balance scenarios: Inquiry > Reservation > Transaction > Finalize. Only enabled business units and linked partners with pre-defined, enabled redemption IDs can carry out ad hoc redemptions.

Examples (Redeemer ID | Redemption ID — description):

  • ClientA | Store_item_soda_123 — Redeem for item in-store or at station
  • ClientB | Catalogue_SafetyKit — Online catalogue redemption
  • ClientC | iTravel_Jan_2023 — Unofficial partner use case
  • ClientD | Investment_Consult — Hypothetical "Linked Partner" use case

Void transaction (partner)​

This feature lets a member void a previous transaction through the Partner API, effectively undoing the original transaction including any points, offer progression, and related data.

  • Validate the request
  • The original transaction must belong to the same member and must not have already been voided
  • The request action in the original transaction must be one that allows voiding
  • If validation is required, the partner in the original transaction must match the partner in the void transaction
  • The system must create the void transaction object, promotion delta object, disbursal objects, points bank update (if FIFO is enabled), member balance update, and a stamp on the original transaction indicating it has been voided

Inbound feeds (operational)​

Activity feed​

This API/feed channels any type of member activity or event — for example, downloading a mobile app, using app features, writing a review, or checking in — into the ES Platform to trigger promotions, complete behavioral offers, or enrich the member's profile. The Send Activity request in the CUX API sends an activity associated with a user.

  • If no activityId is passed in, the system generates a GUID.
  • If businessUnit is passed in, the system evaluates offers belonging to that business unit. Otherwise, offers from any business unit are considered.
note

A single session (correlationID) can process multiple activities. Each request must have a unique activityId.

Ad hoc redeem feed​

This feed accepts ad hoc redemption data from business units or partners.

The Ad Hoc Redeem feed provides business unit and unique identifier information along with redemption data, including the redeemer type (such as PARTNER or BUSINESS_UNIT), a unique redeemer identifier, a unique redemption transaction identifier, the total redemption amount, and the unique identifier and quantity of any related catalogue items (if applicable).

Internal ad hoc redeem feed​

This feed accepts ad hoc redemption data through a Console upload.

The feature must be enabled and a properly-formatted CSV file must be uploaded. For each member, the file includes a unique identifier (loyaltyID, externalIdentifier, accountId, or emailId), a session identifier (correlationId), a business unit, the channel (such as APP, STORE, or ONLINE), the redeemer type, a unique redeemer identifier, a unique redemption transaction identifier, the redemption amount, and a unique identifier and quantity for any related catalogue items.

The upload page shows the names and statuses of previous uploads, including the number of records and errors, the date, and the agent. Agents can download reject files from the Download menu.

Errors are thrown if the feature is not enabled, if any required value is missing or empty, if the reward identifier does not exist, or if the reward exceeds the set limit.

Ad hoc reward feed​

This feed lets a client or their partners issue bulk bonus points via SFTP or Console upload, with related reporting.

The ADHOC_REWARD feed is used by client partners and business units to issue ad hoc bonus points to members without running a promotion in Exchange Solutions. Issuers associate rewards with a reward identifier for reporting purposes.

All points awarded through this method are bonus points. The reward amount can be positive or negative, must be a whole integer, and is subject to the maximum points per transaction limit at the client or program level. Rejected records are collected into an outbound feed file.

Internal ad hoc reward feed​

The INTERNAL_ADHOC_REWARD feed file is used by Console users (such as TSAs) to issue ad hoc bonus points to members in bulk, using a CSV file uploaded to SFTP.

The feature must be enabled and a properly-formatted CSV file must be uploaded. For each member, the file includes a unique identifier, a session identifier (correlationId), a business unit, the channel, the issuer name, a reward identifier, and a reward amount. Errors are thrown if the feature is not enabled, if any required value is missing or empty, if the reward identifier does not exist, or if the reward exceeds the set limit.

Aggregation override feed​

This feed exposes member-level aggregations configured within ES Loyalty — for example, Total Redeemed Points (calendar year), Total Eligible $ Spend (calendar year), and Total Points Earned (calendar year).

If a client migrates to ES Loyalty mid-year, aggregate values must be updated to reflect transactions that occurred outside of ES Loyalty. Historical transaction feeds do not affect aggregations.

Key areas of the feature:

  1. Historical data and aggregates — Historical data migration feeds preload and calculate aggregates. Configuration allows flexibility for adding, overwriting, or appending values.
  2. Design considerations — Aggregates are an internal implementation detail. The feature handles incoming data, manages date ranges, and updates existing aggregates.
  3. Separate feed for aggregates — A dedicated feed manages aggregates, separate from membership tier feeds.
  4. Flexibility and future-proofing — Configuration supports separate CUX API and Console functionality.
  5. Error handling and validation — The system logs errors and warnings for configuration mismatches between account and member-level distinctions.

Supported granularity for the member override feed: DAY, YEAR, QUARTER, MONTH, and others.

Bulk account closure feed​

This feed closes multiple accounts in a single batch operation, with options to zero point balances and anonymize member data.

The client provides a JSON file listing loyalty IDs for accounts to close. Using these IDs, the system closes the account, cancels related loyalty cards, removes partner links (if applicable), and removes the member from any household (if applicable). Optionally, PII data is anonymized and point balances are zeroed.

Bulk offer import feed​

This feature lets clients import externally created offers — such as flyers — into ES Loyalty for behavior recognition. Instead of manually creating up to 150 offers daily in the Console, clients can export offers from their system in a supported format and integrate them efficiently.

The client system administrator provides a JSON file containing offer data, which ES Loyalty ingests. The system operates in two modes:

  • Strict Validation — All validations must pass for every record
  • Flexible Validation — Allows partial ingestion, skipping invalid entries while processing the rest. Flexible mode allows unknown products and stores and can be further customized by relaxing other validation rules

Discretionary feed​

The Discretionary feed adjusts a member's rewards by awarding or removing points in batch for discretionary reasons. Discretionary currency is added or removed from a member's account at the discretion of a customer service agent or other authorized personnel.

The feed includes the loyalty ID, the number of points involved, the reason for the adjustment, unique identifiers for the adjustment action, whether points are being added or subtracted, the related business unit (if any), the transaction date, and the session ID.

Common reasons for adjustments include:

  • Card not swiped at checkout
  • Missing points from an in-store or flyer offer
  • Missing points from a digital offer
  • Points reinstatement — expiry (points lost on account expiry, now being restored)
  • Points reinstatement — fraud (points lost due to a fraud investigation, now being restored)
  • Missing partner card bonus points
  • Other adjustments to the points balance

A bulk discretionary currency issuance corrects multiple account balances in a single operation — for example, when partner card bonus points were not issued due to a technical issue.

Exclusion feed​

The Exclusion feed provides information about products that are not eligible for offer rewards due to regulatory, commercial, or vendor restrictions.

There are different categories of exclusions. For example:

  • Some items may be excluded due to regulations in specific jurisdictions
  • Items from vendors who choose not to participate in the loyalty program
  • Items on which the company decides not to provide rewards

A statement of exclusions must be available to the loyalty program member before they complete a transaction.

Historical transaction feed​

Historical transaction data is loaded into ES Loyalty for use in purchase history targeting, analytical segmentation, seeding purchase data for ES Loyalty Boost, and viewing transaction history for various transaction types. All historical data is stored in Snowflake rather than the Exchange Solutions operational system.

If the data feed option is selected, the historical purchase feed is sent via Exchange Solutions' FTP site. The file goes through the normal cryptography service and is transferred to the Snowflake ADS ingestion S3 bucket. From there, the normal Snowpipe process loads the data.

The HISTORICAL_TRANSACTION feed receives information from the POS or e-commerce solution containing historical purchase and cart information for each retail transaction. This data covers all transactions that occurred before the loyalty program was initiated.

Issuance feed​

This feed carries information from the client about member issuances such as vouchers. For example, if a client issues vouchers quarterly, they use this feed to report those issuances back into the Exchange Solutions system.

Different values can be assigned to the type of issuance — for example, VOUCHER or COUPON. Rewards can be issued in POINTS or DOLLARS, and the status can be set to AVAILABLE, REDEEMED, or EXPIRED for each voucher. Other feed fields include a unique identifier, business unit (optional), the issuance type and unique code, timestamp data (issued, expiry, and optional redemption dates), and any extended data the client wishes to attach. Missing required information returns an error.

Member feed (enrollment/update)​

The Member feed provides full member information to the ESI platform from the client system and is used both to enroll new members and to update data for existing members.

This feed adds and updates members. Deleting and disabling users is handled through the ES Loyalty Console. The feed can be accepted once per 15-minute period. Any transactions referencing newly-enrolled members must arrive after the receipt of this file. Transactions for members without loyalty IDs can be sent with the special loyaltyID keyword ANONYMOUS.

The feed includes the unique member identifier (loyaltyID) along with other member details such as first and last name, birth year and date, gender, address, city, province, zip or postal code, phone number, language preference, and extended data.

Member feed (enrollment/update) enhancement​

Status: Wish List

This enhancement adds data points to the Member feed to support program migration — for example, a firstPurchaseDate field.

This feed adds and updates members, with the same 15-minute acceptance cadence and ANONYMOUS transaction handling as the standard Member feed. It includes additional fields beyond those in the standard Member Feed, such as firstPurchaseDate, that extend the use of EMD.

Member balance update feed​

The MEMBER_BALANCE_UPDATE feed sets up the point balance for members imported into the system and can also be used to correct balance errors after launch.

The feed must be able to set a correct member balance by adding or subtracting (negative values) from the member's account point balance. The feed includes a unique identifier, a session ID (correlationId), the points amount (positive or negative), and a date/time stamp.

Member extended data feed (changes only)​

This feed imports supplemental member attributes — for example, employee flags, survey data, and segmentation scores.

Extended data is optional, program-specific member data used for offer targeting (for example, an analytical segment) or accessed by a CSA or salesperson through the Console (for example, a customer's shirt size). Any key-value pair is allowed, but the maximum data size per customer is 5 kilobytes, with up to 20 unique root-level keys across all members. Attributes must be declared by an ESI TSA before they can be used by the client.

The feed supports up to 20 attributes available for use by the client and Exchange Solutions. EMD supports audience targeting, reporting, and can also be used in Boost in future.

Member household feed​

This feed adds or removes member households — groups of members who aggregate rewards for redemption.

Each household has one Primary member and one or more Secondary members. If the Primary member is removed, the household is disbanded. If a Secondary member is removed, the household continues.

The feed includes unique identifiers for the Primary and one Secondary household member, an action (ADD or REMOVE), and a date/time stamp.

  • "action":"ADD" — If only the primaryLoyaltyID is passed, the household is created and that member becomes Primary. If both primaryLoyaltyID and secondaryLoyaltyID are passed, the household is created with one Primary and one Secondary member.
  • "action":"REMOVE" — If only the primaryLoyaltyID is passed, the household is disbanded. If both IDs are passed, only the Secondary member is removed. The Primary member's household ID must match the Secondary member's household ID or the request is rejected.

Note: neither type of member may be associated with a ghost (unregistered) account.

Membership tier feed​

The MEMBERSHIP_TIER_FEED identifies the tier associated with a member and is used to create and configure the membership tier program.

The feed provides customer profile data, including loyalty and program ID, the program code (a tier program description), the member's rank in the tier program, and their start date.

Partner feed​

The Partner feed identifies client partners with which a member is associated and executes a linking activity such as Add or Delete.

All fields in the feed are required — an error is thrown if any field is missing or empty. The feed includes a unique identifier, the last four digits of the payment card number, the card holder class, the partner card linking activity, a date/time stamp, and the name of the partner providing the payment card.

The PARTNER_LINK feed imports bulk partner linking data for multiple members.

The feed lets clients define the operation for each member: add, remove, update, or no operation. It uses unique identifiers for the member and optionally for the linked partner card (using "last 4" or linkId depending on configuration) and the Bank Identification Number (BIN) of the partner card. Date/time stamps are applied. Optional metadata about the partner card link and the type of linked card (such as PAYMENT_CARD) may also be included.

The return feed delivers error messages for rejections, primarily for missing or empty required values.

Product feed​

The PRODUCT_FEED provides data from the product catalog, including product definitions, categorization (for category, brand, or department offers), and pricing (for offer economics).

The product feed can be sent once per day. It includes standard product codes (by identified type such as GTIN), product names, status (for example, in stock or out of stock), categorization, vendor details, related dates (such as the first date in the catalog), and Extended Data specific to the client that extends their product data profile but is not used by the ESI platform.

Redemption feed​

This feed redeems points in batch for a list of members — for example, for redemption issues manually managed by the retailer or for non-POS redemptions.

Points may not be redeemed correctly if, for example, a POS interface issue prevents redemption transactions from being properly transmitted, or if the retailer wants to issue the value of those points to members as gift cards. A bulk redemption applies the remedy to multiple accounts in a single operation.

Store location feed​

The STORE_FEED provides data about retail store locations for targeting purposes.

The feed provides a store name, country code, province, retail banner (for example, an outlet banner for a chain with multiple banners), and a store code. It can also include extended data specific to the client and the business unit (division) to which the store belongs.

Transaction (purchase) feed​

The PURCHASE_FEED provides transaction details from the POS or e-commerce solution, including purchase and cart information for each retail transaction. It is accepted frequently to keep data up to date.

The feed can be accepted up to once per 15-minute period. Key rules:

  • Any external member IDs referenced in the file must have already arrived in the MEMBER feed, or the record is rejected.
  • If a MEMBER record referenced in the file does not exist in ES Loyalty, the record is rejected and reported in the REJECT feed.
  • Transactions for non-loyalty members can use the special loyaltyId value ANONYMOUS. Anonymous transactions are accepted without a corresponding MEMBER record.
  • A REJECT or REWARD return feed is generated for records that meet the relevant criteria.

Vendor feed​

The VENDOR_FEED enumerates third-party vendors that supply products to the business and may participate in the loyalty program. This feed is used for reporting purposes only.

The feed includes the vendor ID number, the human-readable vendor name, and, if applicable, the business unit within the company associated with that vendor.

Outbound feeds (operational)​

FIFO auto-redeem or FIFO auto-expiry feed​

note

This feed is not available to all new clients. A data warehouse feed is used instead.

The FIFO_AUTO_REDEEM or FIFO_AUTO_EXPIRY feed contains accounts and their First In First Out (FIFO) auto-redeemed or automatically-expired points.

  • FIFO_AUTO_REDEEM — For the automatic redemption of points a set time after they were earned, the client can use this feed to send gift cards containing the redeemed value to those members. This report is generated only if the fifoType is REDEEM for the client.
  • FIFO_AUTO_EXPIRY — For the automatic expiry of points a set time after they were earned, the client can use this feed to sweep the points from the member account. This report is generated only if the fifoType is EXPIRY for the client.

The feed provides unique identifier information for each FIFO operation, along with ISO 8601 and Epoch date/time stamps, the points and dollar amount, and the transaction ID.

Offer data feed​

note

This feed is not available to all new clients. A data warehouse feed is used instead.

The OFFER feed communicates offers to the client's email service provider or for other customer messaging purposes (such as push notifications). The feed includes targeted offer changes, offer template changes, and reward tracking and user stampbook changes. It provides the acceptance state of each offer (NONE, ACCEPTED, COMPLETED) and detailed data about the offer itself.

The OFFER feed is an outbound delta feed that provides offer information to an external email service provider.

Offer targeting details (recordType = OFFER_TARGET): Includes acceptance date/time stamps, the accepted state, and a unique account identifier. Also includes date/time stamps for when the offer became effective, was completed, and expired, a completion count, the loyalty ID and email address for the member, a unique offer identifier, the record type, control group information, and a version number.

Offer template details (recordType = OFFER_TEMPLATE): Includes display, effective, and expiry date/time stamps, offer start and end dates, marketing program identifiers, the activation method (MASS or LOAD-TO-CARD), the product category and subcategory, vendor funding status, offer version, reward type (FLAT, BONUS, or MULTIPLIERS) and amount, embedded local messages, a unique offer code, offer status, qualification type (static or dynamic), maximum completions, and offer rank (priority).

Scheduled member marketing feed​

note

This feed is not available to all new clients. A data warehouse feed is used instead.

This feed communicates member data to the client's email service provider or for other customer messaging purposes.

If there is a spend threshold and it has not been met, the on-hold amount equals the current account balance. If there is no spend threshold, or it has been met, the on-hold amount equals the number of points on hold.

Only accounts in good standing with a LoyaltyID are included. The following are excluded:

  • AccountStatus = Closed, Deceased, or Cancelled
  • CardStatus = NON_LOYALTY
  • Accounts without an emailAddress

The feed includes unique identifiers, loyalty ID and business name, comprehensive member information (email, name, language preference, localization flag), program participation data (tier, opt-in, LAD, point and dollar balance, account suspension and expiry flags), and member statistics (total rewards and redemptions, total eligible spend by month and year).

Scheduled report reject feed​

The REJECT feed provides information about records rejected from any other feed.

For each inbound feed file with one or more records that could not be uploaded or processed, the Reject feed provides:

  • Header file information indicating the file name, number of successful records, and number of failed records
  • If a file completely failed to upload: details about the attempted inbound feed and the reason for failure
  • If only some records failed: details about each rejected record, including the original JSON request, a unique identifier for the failed record, technical rejection reason, record status (always REJECTED), the source file name, the failure reason code, and a user-friendly message

Scheduled report reward feed​

note

This feed is not available to all new clients. A data warehouse feed is used instead.

The REWARD feed communicates points information for reconciliation purposes or to support an external point bank.

This feed reports rewards provided to members. It includes the loyalty ID, a correlation ID for the original transaction, details about points earned and their categories (base, bonus, targeted, and total), and information about the related offer (unique offer code, description, points earned, and category).

The following transactions are not included in the REWARD feed:

  • Anonymous POS transactions
  • Activity transactions that did not earn points

Scheduled burn reconciliation feed​

note

This feed is not available to all new clients. A data warehouse feed is used instead.

This reconciliation feed extracts all currency bank activity for audit, reconciliation, financial reporting, and backup purposes. Detailed transaction data is sent to the partner to reconcile against the system of record.

Detailed transaction data includes unique transaction identifiers, card numbers, transaction amounts, terminal information (for POS transactions), and points earned and redeemed.

The client process identifies unreconciled activity and escalates it to ESI. A standard set of outbound data feeds also lets partners reconcile against program metadata (such as product, promotion, and offer data). In the absence of a transaction-level reconciliation process, aggregate data can be sent for reconciliation purposes.

Scheduled earn reconciliation feed​

note

This feed is not available to all new clients. A data warehouse feed is used instead.

This reconciliation feed extracts all currency bank activity for audit, reconciliation, financial reporting, and backup purposes. It provides transaction-based reconciliation reporting for each specific earn transaction.

Details are provided for each specific earn transaction.

Account and loyalty card feeds (DWH)​

Account feed​

The Account feed stores customer state for each card account. Note that the Available Point Balance does not account for daily redemption limits — an additional RedeemablePointBalance value is required for this purpose.

The Account feed provides:

  1. The unique account identifier and status
  2. The version number and date for the last update in the data table
  3. The created, registration, and last updated dates for the account
  4. A unique ID for a loyalty card associated with the account, along with the card status (ACTIVE, SUSPENDED, LOST_OR_STOLEN, DAMAGED, FRAUD_ABUS, CANCELLED, or null)
  5. A Boolean switch indicating whether the POS operator should ask for the customer's email address
  6. Current total and available point balances, and whether the customer is a client employee
  7. A card swipe counter indicating how many times cards on this account have been swiped
  8. An external identifier used by the client (if any)
  9. The registration channel (for example, APP, WEBSITE, STORE)
  10. Customer information: first and last name, email address, city, postal or zip code, street, province or state, and country
  11. The name of the agent making profile changes
  12. The channel through which a profile change was made (POS, SYSTEM, CLIENT, or AGENT)

Loyalty card feed​

The loyalty_card table lists each historical loyalty card an account has had, including the current card number.

The Loyalty Card feed provides:

  1. A unique ID for the loyalty card
  2. The version number and date for the last update in the data table
  3. The unique account identifier
  4. The card status (ACTIVE, SUSPENDED, LOST_OR_STOLEN, DAMAGED, FRAUD_ABUSE, CANCELLED, or null)
  5. The created, issued/registered, and last updated dates for the loyalty card

Activity feed (DWH)​

Lists account activity including audit details, activity status, any related transaction ID, and date/time and activity data.

The Activity feed provides:

  1. The account ID associated with the token
  2. A unique activity identifier
  3. The version number and version date of the activity update
  4. The activity type — for example, FIRST_TIME_LOGIN
  5. The associated unique identifier for the loyalty card
  6. Audit details for the activity
  7. The activity status — for example, REWARDED
  8. The transaction ID linked to the activity
  9. Any additional activity data
  10. The date/time stamp for when the activity occurred

Account token feed​

Contains point reservation tokens associated with an account. Points are reserved in a separate API call from the point redemption.

The Account Token feed provides:

  1. The account ID associated with the token
  2. The token itself
  3. The version number and version date of the account token update
  4. The date/time stamps for when the token was created and when it will expire
  5. The number of points reserved by this token

Contains partner payment cards linked to loyalty accounts, along with the status and metadata of the partner payment card.

The Payment Card Link feed provides:

  1. The unique account identifier
  2. A unique identifier for the partner associated with the payment card (for example, MEGABANK)
  3. The last four digits of the payment card number
  4. The version number and date for the last update, and the date and time when the version expired
  5. The created, last updated, linked, and unlinked date/time stamps; if the card was linked or unlinked more than once, the linked stamp refers to the most recent instance
  6. The link type: PAYCARD_LAST4 or PAYCARD, depending on how the payment card is identified
  7. The type of card holder: Retail or Business
  8. The type of payment card: C (credit) or D (debit)
  9. A unique link ID when the link type is PAYCARD
  10. The current status of the linked payment card
  11. A Bank Identification Number (BIN) — the first 4–6 digits on the payment card identifying the issuer

Contains partner payment cards linked to loyalty accounts, along with the status and metadata of the partner payment card.

The Partner Card Link feed provides the same fields as the Payment Card Link feed, with the addition of a current status field that indicates LINKED or UNLINKED.

Scheduled member marketing feed (DWH)​

This feed communicates member data to the client's email service provider or for other customer messaging purposes.

Same structure as the operational Scheduled member marketing feed. Accounts that do not meet the inclusion criteria (active status, loyalty ID, and email address) are excluded.

Scheduled burn reconciliation feed (DWH)​

This reconciliation feed extracts all currency bank activity for audit, reconciliation, financial reporting, and backup purposes. It provides transaction-based aggregated point reconciliation reporting for redemptions.

The feed includes enhanced validation to verify critical data against other reliable sources. Exchange Solutions uses an internal reconciliation process because it is not the System of Record (SoR) for many clients.

The feed checks for TRANSFER_OUT, REDEEM, or HOUSEHOLD_REDEEM transaction parts to identify burn transactions. Snowflake does not enforce data uniqueness, so duplicates are possible — ongoing checks are in place to detect duplicates and fail a data transfer process if they are found. Due to the enhanced validation process, validated data may not be available for several days.

Detailed transaction data includes unique transaction identifiers, card numbers, transaction amounts, terminal information, and points earned and redeemed.

Scheduled earn reconciliation feed (DWH)​

This reconciliation feed extracts all currency bank activity for audit, reconciliation, financial reporting, and backup purposes. It provides transaction-based aggregated point reconciliation reporting for rewards. Enhanced validation is used to verify critical data against other reliable sources.

The feed includes all transactions along with the number of points earned. Snowflake does not enforce data uniqueness, so ongoing duplicate checks are in place. Validated data may not be available for several days due to the enhanced validation process.

Details are provided for each specific transaction.

Transactional data feeds (DWH)​

Session feed​

A session is a series of API calls made in the context of a single customer interaction — for example, a checkout at POS or a single login to a web or app. The primary key is provided by the system initiating the session.

The Session feed provides:

  1. A unique session identifier
  2. The version number and date for the last update in the data table
  3. A unique account ID and a unique loyalty card ID
  4. A Boolean tracker to identify if the card was swiped or keyed in
  5. The source channel: POS, MOBILE, WEB, CONSOLE, SYSTEM, APP, or null
  6. Points redeemed and earned in the session, and the point balance at the start of the session
  7. The net difference in points that occurred during the session
  8. The status (OPEN or CLOSED) and the date/time stamp of the session start

Transaction feed​

A transaction represents any point earning or point spending event — essentially a customer's point banking statement.

The Transaction feed provides:

  1. A unique transaction identifier
  2. A unique account identifier
  3. The source channel: POS, MOBILE, WEB, CONSOLE, SYSTEM, APP, or null
  4. A unique store identifier
  5. The eligible transaction amount
  6. A Boolean to track why a zero-point transaction occurred
  7. The account status (ACTIVE, EXPIRED, SUSPENDED, DECEASED, CLOSED, CANCELLED, UNREGISTERED, or null)
  8. A Boolean to track whether the account is eligible to earn
  9. The default loyalty card status
  10. The date/time stamp for when the transaction was processed
  11. The API call that triggered the reward calculation
  12. The dollar amount of the basket or cart
  13. The date/time stamp for the POS transaction (may be backdated for SAF calls)
  14. The net point amount, balance after the transaction, and balance before the transaction
  15. The agent and reason if discretionary points were awarded
  16. The opt-in prompt result from the POS (deferred, declined, accepted, or null)
  17. The email prompt result from the POS
  18. Base points and bonus points earned, excluding partner points
  19. Total targeted points earned, excluding loyalty targeted points
  20. Discretionary points earned
  21. Total points redeemed and the redemption dollar value
  22. Partner ID, partner base and bonus points earned, and partner targeted points earned
  23. A call ID — a unique identifier generated internally if missing from the transaction
  24. The agent name if a profile update was made
  25. The transaction and account IDs associated with transferred points

Transaction_Tender feed​

A transaction represents any point earning or point spending event. The tender type is the payment method — for example, VISA, CASH, DEBIT, COUPON, MASTERCARD, or AMEX.

The Transaction_Tender feed provides:

  1. The unique transaction identifier
  2. A unique identifier for each tender object
  3. The tender type: VISA, CASH, DEBIT, COUPON, MSTCARD, or AMEX
  4. The first six digits of the payment card number (null if not sent)
  5. The last four digits of the payment card number (null if not sent)
  6. The type of card holder: Retail or Business
  7. The payment card type: C (credit) or D (debit)
  8. The amount paid by this payment card
  9. An identifier for any linked partner (or null if not applicable)
  10. A call ID — generated internally if missing from the transaction
  11. A Boolean to indicate if this account is associated with a link ID

Transaction_Promo_Audit feed​

Contains details about the promotions recognized in a transaction.

The Transaction_Promo_Audit feed provides:

  1. A unique promotion transaction identifier used to join this data with associated details
  2. The transaction ID this audit is linked to
  3. The client-specific reporting identifier associated with the promotion
  4. A promotion description — for example: "Get 500 bonus points when you spend more than $20."
  5. The unique offer code — for example: 008GET500
  6. The version of the promotion used in this transaction
  7. A unique name for the promotion tier, if applicable
  8. The number of points provided as a reward
  9. The customer spend eligible for the reward
  10. A message associated with the audit — for example: "EXCLUSION: User is not targeted for this promotion."
  11. The number of items recognized by the promotion
  12. The promotion category: BASE, BONUS, or TARGETED
  13. The unique partner identifier — for example: MEGABANK
  14. A call ID — generated internally if missing from the transaction

Transaction_Promo_Audit_Detail feed​

Contains further details about a specific TransactionPromoAudit.

The Transaction_Promo_Audit_Detail feed provides:

  1. A unique promotion transaction identifier used to join this data with associated details
  2. The transaction ID this audit is linked to
  3. The spend associated with this item
  4. The number of items considered
  5. The unique identifier of the item considered
  6. The type of item considered — for example: SKU
  7. The number of points disbursed for an individual SKU for a specific offer; data type is float, as individual points can be split between products in the basket
  8. A call ID — generated internally if missing from the transaction

Promotion and targeted offer data feeds (DWH)​

Targeted_Offer feed​

A list of available targeted offers attached to an account.

The Targeted_Offer feed provides:

  1. The account ID targeted
  2. A code indicating the promotion to which this offer belongs
  3. A sequential version number and the date/time stamp for when the offer version took effect
  4. The version of the offer
  5. The version of the offer being accepted
  6. The current acceptance state: NONE, COMPLETED, DECLINED, or ACCEPTED
  7. The number of times the offer has been completed
  8. The date/time stamp for when the offer becomes active
  9. The date/time stamp for when the offer expires
  10. The maximum number of times this offer may be completed
  11. The date/time stamp for when the offer was last completed
  12. The date/time stamp for when the offer was accepted

Live_Promotion feed​

A list of promotions that are currently active — that is, whose EffectiveDate and ExpiryDate bracket the current date.

The Live_Promotion feed provides:

  1. A unique identifier for the offer
  2. The version of the promotion
  3. A sequential version number and the date/time stamp for when the offer version took effect
  4. The date/time stamp for when activation of the promotion took place
  5. The date/time stamp for when approval took place, and the approving user
  6. The version this promotion was based on
  7. The valid channel for the offer: POS, MOBILE, WEBSITE, CONSOLE, SYSTEM, APP, WEB, or null
  8. The date/time stamp for when the promotion becomes active
  9. The date/time stamp for when the promotion expires
  10. The promotion status: ACTIVE or EXPIRED
  11. The submission date/time stamp and the submitting user
  12. The promotion category — for example: PROMO
  13. The promotion sub-category — for example: BONUS
  14. The activation method: MASS or LTC
  15. A Boolean to indicate whether global exclusion rules are disabled
  16. A long description of the promotion
  17. The name of the promotion
  18. The rank of the promotion
  19. An associated award group
  20. The sections of the promotion description
  21. A Boolean to indicate whether the promotion is vendor-funded
  22. A Boolean to indicate whether the promotion is dynamic

Promotion_Tier feed​

Represents the reward tiers applicable to a given promotion.

The Promotion_Tier feed provides:

  1. A unique identifier for the offer
  2. The version of the promotion
  3. A sequential version number and the date/time stamp for when the offer version took effect
  4. A unique name for the tier
  5. The precedence of the tier (evaluated in ascending order)
  6. The number of points or a point multiplier
  7. The reward type: FLAT or MULTIPLIER
  8. The tier threshold category: SPEND or UNIT
  9. The tier threshold sub-category: AMOUNT or COUNT
  10. The tier threshold type: MIN, MAX, or PER
  11. The actual value of the tier threshold

Promotion_Metadata feed​

Contains client-provided reporting metadata for a given promotion.

The Promotion_Metadata feed provides:

  1. A unique identifier for the promotion
  2. The version of the promotion
  3. A sequential version number and the date/time stamp for when the offer version took effect
  4. Two different tags for grouping promotions, and a description of a promotion-grouping event
  5. A client-specific reporting identifier associated with the promotion
  6. The number of days the offer is active for each user
  7. The number of times this offer can target a user
  8. The action carried out by the activity — for example: MEMBER_REGISTRATION

Household feed​

Provides daily changes made to a household account by any household member.

The Household feed provides:

  1. A unique account identifier
  2. A unique household identifier
  3. The member's role in the household: PRIMARY or SECONDARY
  4. The date/time stamp for when the member joined the household
  5. The unique identifier for the inviter
  6. The user agent that made the household update
  7. The channel where the change was made — for example: POS

Frequency_Offer_Progress feed​

This feed lets clients track progress on frequency offers so that timely email communications can be sent to increase customer lifetime value.

Examples:

  1. "Jane Doe is 1 transaction away from completing the offer: 'Purchase 2 Mars bars in 2 separate transactions'."
  2. "James Doe, you are only $10 away from completing the 'Spend $50 in any transaction to earn 3,000 points' offer."

Requirements include:

  1. Tracking frequency offer progress in the feed for both spend amount and quantity
  2. A Data Warehouse feed containing the necessary attributes to track frequency offer progress

The Frequency_Offer_Progress feed provides:

  1. A unique account identifier
  2. The account identifier type (ACCOUNT_ID or LOYALTY_ID)
  3. A unique promotion code — for example: TIER_PROGRESSION_OFFER_TIER2
  4. A description of the promotion — for example: "Spend $100 to get 3,000 points."
  5. The date/time stamp for when the offer version took effect
  6. The date/time stamp for when the offer version expires
  7. The number of times the offer was completed
  8. A Boolean to indicate if the completion limit was reached
  9. The maximum number of completions allowed
  10. The count of rewards earned per completion
  11. The offer type: SPEND or QUARTERLY
  12. The balance needed to reach the spend threshold
  13. The total amount spent on the offer
  14. The amount spent above the threshold
  15. A list of transactions associated with the offer
  16. The completion percentage based on the contribution type

Product_Spotlighting feed​

A list of available targeted offers attached to an account, enhanced to support product spotlighting and compliance.

This feature enhances DWH feeds to include product identifiers for eligible products. It supports compliance traceability — for example, allowing compliance auditors to verify that the organization has a record of product identifiers (usually SKUs, but potentially UPC or GTIN) for each offer, enabling appropriate reports for stakeholders to refine marketing campaign parameters.

The feed returns a list of product identifiers and matching aliases for active offers only. Aliases are returned only if data volume is not excessive.

The main source of the feed is the cart selector within the promotion table. The cart selector JSON is converted into a list of eligible products. If a CSV file of eligible products was uploaded in the Console, that list is used directly.

The feed is provided through a daily upload or through Snowflake synchronization. Redemption offers and category redemption offers are included; activity offers are not. The feature can be fully enabled or disabled per client. The product code and product code type are also configurable (UPC, SKU, GTIN, or another identifier).

Fulfillment feeds (DWH)​

Blackhawk Network direct deposit feed​

This feed supports loyalty programs that allow points to be redeemed for cash, applied as a direct deposit. Payment data is sent through the Blackhawk Network.

Clients currently receive a file with bank account details and redemption amounts, which they send to a third-party payout processor. Exchange Solutions replicates this functionality using Blackhawk Network as the processor. Signing a partnership agreement with Blackhawk Network is required.

For US clients, the Blackhawk file format includes the email address and reward amount. BHN sends emails to members to collect their banking details. Members click the link, provide their banking details, and BHN completes the fund transfer.

Fulfillment direct deposit feed​

This feed supports loyalty programs that allow points to be redeemed for cash, applied as a direct deposit.

When this option is selected, the Direct Deposit file is generated and retrieved by the client, who then sends it to a third-party payout processor to complete the fund transfer. The file is generated by Exchange Solutions on a configured weekly cadence. The client retrieves the file from ES Loyalty and initiates transfers using their payout processor software as part of back-office operations.

Fulfillment statement credit feed​

This feed supports B2B loyalty programs that allow points to be redeemed for cash applied as a statement credit to reduce payment required for products purchased.

When this option is selected, a statement credit file is generated. The client uses this file and processes the statement credit through their internal business process.

Phone number enablement​

Business definition​

This feature supports SMS marketing for loyalty program members. SMS marketing delivers high member engagement, increases revenue and average order value, and is the most direct way for members to engage with time-sensitive information in real time. It complements other marketing channels and improves member loyalty and engagement.

Salesforce Marketing Cloud (SFMC) integration​

Trigger email send​

This feature triggers an email to a member when a specific event occurs — for example, if a member has a linked partner payment card, they may receive an email detailing the transaction if they used the card, or a reminder about card benefits if they did not.

This feature triggers emails to members through Salesforce Marketing Cloud (SFMC). Messages can also be triggered for events such as enrollment, first login, account adjustments, point redemption, voiding a redemption, frequency offer progress, account suspension, badge earned, partner linking, member household updates, and imminent points expiry.

ESP data sync​

Syncs with SFMC directly when any of the following occur: account updates, opt-in preference changes, promotion template attribute changes, targeted offer reward tracking and completion status, and partner link status.

A set of marketing integrations synchronize key data from ES Loyalty with a marketing provider to support transactional emails and business email campaigns. Three integration modes are supported:

  1. Near-realtime integrations — Two capabilities:

    • Transactional emails — Triggered when specific ES Loyalty actions occur (for example, registration confirmation, redemption, partner linking/unlinking, points transfer, password reset, email address update)
    • Low-latency data sync — Two sub-modes:
      • Push — Keeps the marketer's data current with changes in ES Loyalty, including member profile updates, opt-in management, promotion maintenance, targeted offer tracking, and partner link status
      • Pull — Retrieves opt-in preferences, partner link status, and other member settings from the marketer

  2. Batched, file-based synchronization — Generates files on a schedule (time- or size-based) containing changes across the entire member population. Files are sent to an SFTP site at the marketing provider or used to invoke a bulk import/export API. Currently supports Push operations only.

  3. Snowflake Secure Data Sharing — Allows data ingested or derived in an ES Snowflake instance to be securely shared with a client's Snowflake instance. This is not near-realtime — operational data is gathered in an S3 bucket and ingested into Snowflake on a schedule (typically daily). This enables bulk refreshes and allows the client to use this data across any system that can integrate with their Snowflake.

Sync aggregations​

This feature synchronizes member aggregations from ES Loyalty to Salesforce Marketing Cloud through the Data Integration Gateway (DIG). It enables aggregated loyalty data — for example, monthly points earned and yearly spend amounts — to be transmitted to SFMC in near real time.

The enhancement is implemented within DIG and available for use with the SFMC Connector. Additional work may be required to support this capability across other connectors. Member aggregations sync automatically when the feature is enabled.

  1. Aggregated member data is synchronized from ES Loyalty to SFMC when the feature is enabled
  2. Synchronization occurs in near real time
  3. Aggregations are based on the Exchange Solutions Aggregations framework, rolling up member transactions across defined time granularities (for example, monthly and yearly)
  4. Implementation effort may be required for other ESP connectors

This feature enables marketers to perform richer customer segmentation, create personalized campaigns using aggregated loyalty metrics, and execute behavior-driven audience strategies using multiple time granularities.

Sync issuance/vouchers​

This feature synchronizes voucher data from ES Loyalty to Salesforce Marketing Cloud through the Data Integration Gateway (DIG). It transmits voucher data to SFMC whenever voucher data is updated, supporting outbound communications and campaign execution.

The enhancement is implemented within DIG. Additional work may be required to support this capability across other connectors. Voucher data syncs automatically when the feature is enabled.

  1. Voucher data is synchronized from ES Loyalty to SFMC when the feature is enabled
  2. Synchronization is triggered whenever voucher data is updated (via the issuance feed)
  3. The feed includes voucher lifecycle events: AVAILABLE → REDEEMED → EXPIRED
  4. Implementation effort may be required for other ESP connectors

This feature enables marketers to notify members on voucher status, send reminders for vouchers nearing expiry, and leverage behavioral strategies such as loss aversion to increase engagement.

Email native integration (via Data Integration Gateway)​

This feature provides bulk and triggered loyalty data to support email messages about redemption, offers, partner linking, points transfer, badges, point expiry, and other email types.

ES Loyalty has native integration with SFMC that supports core loyalty marketing communications, including both batch and near-realtime integrations. Exchange Solutions can trigger communications through SFMC based on the state of the client's offers, including current offers, reminders, and confirmations.

SMS native integration (via Data Integration Gateway)​

This feature provides bulk and triggered loyalty data to support SMS messages about redemption, offers, partner linking, points transfer, badges, point expiry, and other SMS message types.

The integration between Exchange Solutions and SFMC manages SMS subscriptions for members. A data extension tracks loyalty members' phone numbers based on their marketing SMS sign-up numbers, capturing both registered and unregistered activities and new sign-ups classified as non-loyalty accounts. ES Loyalty reads and writes to this data extension to manage SMS subscriptions. An automation in SFMC updates subscription status from the SFMC mobile connect module back to this data extension every 20 minutes in production.

Marketo integration (via Data Integration Gateway)​

Full native integration​

Trigger, bulk, and enablement integration for standard ESP-loyalty functionality.

  • Use existing file generation and translate file entries to marketing bulk API calls
  • Introduce a new module for ESP integration, starting with Marketo as the first ESP
  • Completely decoupled from Loyalty — begin by syncing promotional offers to ESP
  • Respects ESP service limits and resumes after hitting them
  • Future scope: decouple remaining ESP integration points (triggered send, etc.) per ESP provider
  • Does not currently account for syncing extended member data

DotDigital integration (via Data Integration Gateway)​

Trigger email send​

This feature triggers an email to a member when a specific event occurs — for example, if a member has a linked partner payment card, they may receive an email detailing the transaction if they used the card, or a reminder about card benefits if they did not.

This feature triggers emails through Dot Digital. Messages can be triggered for events such as enrollment, first login, account adjustments, point redemption, voiding a redemption, frequency offer progress, account suspension, badge earned, partner linking, member household updates, and imminent points expiry.

Optimove integration (via Data Integration Gateway)​

Native integration​

Trigger individual data sync to support summary and journey-type email campaigns, and bulk data transfer focused on targeted offers.

Exchange Solutions has a partnership with Optimove, a science-first marketing relationship hub. For practical purposes, Optimove can be considered a platform with combined CDP, CRM, and ESP capabilities. This partnership benefits joint clients by combining ESL's strength in offer personalization with Optimove's strength in orchestrating CRM journeys.

ESL leverages Optimove's CDP and ESP capabilities by:

  1. Syncing loyalty data points to Optimove
  2. Supporting personalized loyalty email communications sent via Optimove
  3. Syncing promotional offers and member interactions with promotions to Optimove

Email Service Provider (ESP) integration​

Email integration — member synchronization​

This enhancement to the feed tracks progress of frequency offers to provide marketers with additional channels for sending timely communications to increase customer lifetime value.

The feature lets clients track frequency offer progress so that email communications can be sent — via the client's existing ESP integration — to inform members of their offer progress.

Examples:

  1. "Jane Doe is 1 transaction away from completing the offer: 'Purchase 2 chocolate bars in 2 separate transactions to complete the offer.'"
  2. "James Doe, you are only $10 away from completing the 'Spend $50 in any transaction to earn 3,000 points' offer."

Two outbound feeds support ESP communication:

  • Offer Feed — Provides offer template data, information about members who receive those offers, and progress toward completing them (including frequency offers)
  • Member Marketing Feed — Provides member profile and program data

Use case 1: As a marketer, I want to use the offer feed to track frequency offer progress in both spend amount and quantity.

Use case 2: As an analyst using the data warehouse feed, I want to track frequency offer progress in both spend amount and quantity.

Email integration — targeted offer data synchronization​

This feature provides necessary promotion data — including point balance, offer details, and targeting — from ESI to be consumed by an ESP (for example, SFMC) to enable outbound communications. The OFFER feed communicates offers to the client's ESP or for other customer messaging purposes. It provides the acceptance state of each offer and detailed offer data. Offer acceptance is expected to take place through the Customer Experience API. The enhancement includes frequency offer progress.

The feed is generated every 15 minutes, or whenever 50 MB of data is generated, whichever comes first.

Email integration — extended member data synchronization​

Extended member data attributes are synced from ES Loyalty into SFMC for targeting or content personalization. This is optional, program-specific consumer data that can be used for offer targeting (for example, an analytical segment) or accessed by a CSA or salesperson from the Console (for example, a shirt size).

Any key-value pair is allowed (camel case naming convention is strongly recommended), but the maximum data size for extended data per consumer is 5 kilobytes, with up to 20 unique root-level keys across all members.

Agents can also view Extended Member Data for individual members on a per-member basis in the Console.

Email integration — individual data sync (API/feed)​

This feature provides event trigger type and targeting data from ESI to an ESP for outbound communications. It must be able to trigger specified emails to relevant members in an ESP based on an event in ESI — for example, a redemption.

When a user performs a redemption, they receive an email informing them of the redeemed amount (in dollars, for Kent), the store number where the redemption was made, and the date and time of the redemption. An account must be registered to redeem and therefore must be registered to receive a redemption transactional email.

Modular ESP integrations​

This feature enhances the ease and depth of key integrations across marketing platforms and ESPs.

Exchange Solutions has identified generalizable patterns across marketing platforms (such as Marketo and Selligent) and ESPs. The goal is to develop standard approaches for triggering scheduled and event-triggered emails to loyalty program members, requiring as little custom work as possible per platform.

Two integration patterns:

Triggered sends:

  • A user activity generates an event that immediately triggers an email to that user
  • Specific to user behavior
  • Works on a single channel (email only)

Marketing feeds:

  • A user uploads a file containing campaign information to SFTP
  • The file is processed and ingested into SFMC
  • An email blast is sent to all users identified in the campaign

Triggering data can be sent through an outbound feed or through an API.

Data migration​

Member migration​

Data migration is the preparatory phase of onboarding a new client, in which existing member data from their current loyalty program is moved into ES Loyalty or another app.

Data migration includes moving the following data into ES Loyalty:

  • One-time migration of loyalty card numbers (possibly through the existing card loading mechanism in ESL)
  • Member data — enhanced member feed
  • Ghost card accounts — This is to be decided by the technical team handling the data migration
  • Last activity date — new feed
  • Point balances — new feed
  • Householding data — new feed
  • Partner linked data (financial or non-financial partner) — existing Partner Feed or Partner Programs API
  • New card number generation (after cut-off period) — enhancement needed to ensure newly generated card numbers are net new

Transaction migration​

Data migration of selected historical transaction (purchase history) data — typically 1–3 years — from the legacy system to ES Loyalty.

Depending on client requirements and feasibility, the migration may include 1–3 years of historical transaction data, potentially including:

  • Partner linked data transaction history
  • Loyalty data transaction history
  • Ghost card data transaction history
  • Non-loyalty data transaction history (for analytics purposes)

Data sync​

Member sync​

This syncing can occur both during and after the program transition and migration period.

As part of the Suncor migration to the ES Loyalty platform, member data must remain consistent across three phases:

Pre-Production Data Migration (t0)

During this phase, when SOR is false, the following feeds are used to migrate and update members and household data:

  • Member feed
  • Member Household feed

Transition Period (t1)

SOR remains false. The client calls API endpoints to perform the following actions:

  • Member enrollment
  • Update member profile
  • Suspend or reinstate an account
  • Add or remove household
  • Change card status
  • Replace card
  • Partner linking

In this phase, the loyaltyId passed in requests may or may not already be registered in ES Loyalty, and the system handles both scenarios correctly.

Production (t2)

All features from the previous phase work as standard.

Transaction sync (inbound)​

This feature supports inbound transactions into ES Loyalty from pre-cut-over sites during a client onboarding, prior to cutting over to ES Loyalty.

A generic transactions API was created to accept inbound transactions from pre-cut-over sites. As part of this API:

  • A new session is started (System)
  • The transaction model is constructed based on the request body
  • The transaction is persisted and tagged to indicate it is a special type
  • The member's account balance is updated
  • The Promo Engine is not called
  • Metric and Aggregation (ODS) processes are skipped
  • FIFO is not supported for this transaction type

Transaction sync (outbound)​

This feature supports outbound transactions to cut-over sites — that is, sites already using ES Loyalty.

A common payload is published to the client's Kafka queue. High-level implementation steps:

  1. Create a new event processor in ESL to publish transaction data from cut-over sites to the client's Kafka queue
  2. Listen on all requestAction types except HISTORICAL_TRANSACTION
  3. Create a new DTO object containing all relevant transaction data and push it to Kafka — this is a generic, non-client-specific payload for reuse in future
  4. Apply data-cleansing rules to prevent PII from being published
  5. Guaranteed delivery:
    • Retry sending the message 3 times on error
    • If all retries fail, push the message to a dead letter queue (SQS)
    • Configure an alarm for messages moved to the dead letter queue

Member profile changes SOR data sync​

Some clients store member profile information in their own system of record (SOR). When a call center receives a request to change a loyalty member's profile, the changes made in the Console are synced back to the client's SOR.

The following member profile fields are synced when changed:

  1. First name
  2. Last name
  3. Date of birth
  4. Gender
  5. Phone number
  6. Street address
  7. City
  8. Province
  9. Postal code
  10. Account associations

Note: Extended Member Data is not synced to the SOR. EMD originates from the SOR when uploaded into the Console.

Member profile data is synced through Kafka with a Guaranteed Delivery mechanism using a Dead-Letter Queue (DLQ) for messages that cannot be delivered due to errors.

When activated, the SOR data sync feature may cause throttling issues for Salesforce Syndication. A new parameter, AccountProcessingMode, addresses this:

  • HIGH_THROUGHPUT — Uses a new pipe to stream data to an SQS queue (for clients not using Salesforce)
  • LOW_THROUGHPUT — Uses the existing DynamoDB triggers (for clients using Salesforce)

Retail/client data integration​

Advanced experiential loyalty powered by Cataboom​

Comprehensive gaming, badging, and prizing functionality designed to boost member engagement with the loyalty program or brand, deliver engaging experiences, and capture valuable zero-party data to enhance downstream personalization.

The Cataboom partnership helps Exchange Solutions capture and engage members with on-brand gamified experiences and prizing that motivates targeted behaviors. Cataboom drives loyalty program member acquisition and engagement through:

  • Targeted KPIs:
    • For acquisition: number of enrollments, loyalty penetration (example tactic: instant win or sweepstakes)
    • For member engagement: active rate (or reduced churn), redemption rate, digitally-engaged members percentage, frequency of visits and purchases (example tactic: collect and win — member completes tasks to qualify)
  • Chance-to-win entry for signing up
  • Gamified experience to highlight program features and benefits

First- and zero-party data collected through games enriches member insights and offer targeting.

Cataboom can also support ES Engage offer engagement — for example, members may unlock an offer by completing a simple task such as watching a video or engaging in a poll or quiz. First-party or zero-party data can then be used for member insights and offer targeting, attributed to purchases or digital and physical traffic drivers.

Other data integrations​

Agent audit — Splunk​

This feature syncs agent audit details to the client's Splunk environment. Splunk connection details (endpoint, ID, and secret/password) are stored in an ES Loyalty secret.

An activity log tracks agent activities and allows drilling into specific details of agent events.

Agent action types:

  • DISCRETIONARY_TRANSACTION — An agent awarded or removed points from a member account
  • UPDATE_PROFILE — An agent updated a loyalty member's profile
  • CREATE_NOTE — An agent created a note about a loyalty member
  • UPDATE_NOTE — An agent edited a note about a loyalty member
  • DELETE_NOTE — An agent deleted a note about a loyalty member
  • CREATE_PROMOTION — A marketer created a loyalty promotion
  • UPDATE_PROMOTION — A marketer edited a loyalty promotion
  • DELETE_PROMOTION — A marketer deleted a loyalty promotion
  • TRANSFER_POINTS — A marketer transferred points from one account to another
  • ACCEPT_OFFER — An agent accepted an offer on a customer's behalf
  • UPDATE_CARD_STATUS — An agent updated the status of a member's loyalty card (for example, from ACTIVE to CANCELLED)
  • UPDATE_ACCOUNT_STATUS — An agent updated the status of a member's account (for example, from ACTIVE to DECEASED)
  • REPLACE_CARD — An agent replaced a member's card
  • UPLOAD_TARGETING_LIST — A marketer uploaded a customer targeting list
  • AWARD_PPE_POINTS — An agent entered a receipt number to award points to a customer after the fact (the customer did not swipe their card and had not previously earned points)
  • CREATE_BANNER — A marketer created an advertising banner
  • UPDATE_BANNER — A marketer updated an advertising banner
  • DELETE_BANNER — A marketer deleted an advertising banner

For each activity, the data includes the before and after state. A useful starting point is to build a report of action and time. For some specific actions — particularly DISCRETIONARY_TRANSACTION and AWARD_PPE_POINTS — recording the point amounts is recommended.

Snowflake data integration​

This feature integrates ES Loyalty with the client's Snowflake instance to facilitate program data import into ES Loyalty.

With Snowflake data sharing, Exchange Solutions can access and exchange required data directly with the retailer's Snowflake account to run modular loyalty and personalized offer solutions, without the need for complex ETL. This requires that the retailer uses Snowflake and that all required data resides and is accessible in Snowflake.

Benefits for retailers:

  1. Faster speed to market — no feed ETL setup required
  2. Cost-effective — no ongoing ETL management
  3. Data remains centralized — avoids data duplication at the retailer
  4. All data resides in one place (the client's Snowflake)
  5. Simplified data enrichment — ES product data shared back directly to Snowflake for easy unification and enrichment
  6. Accelerated model training — new data elements easily accessed to update and train personalized offer intelligence more quickly
  7. Product implementation shortened from months to weeks
Last updated on