Getting Started with Loyalty
Sparkfly Loyalty provides a comprehensive solution for building and administering Loyalty programs, featuring flexible point management, catalog-based member rewards, and seamless integration with the core Sparkfly Offers Platform.
API Reference
The full API reference for Sparkfly Loyalty can be found here: Sparkfly Loyalty API Reference
Terminology / Conceptual Overview
The following sections briefly cover the different entities used throughout the API, describing their terminology, basic setup, and how they relate to each other and the broader Sparkfly Loyalty platform.
Programs
The highest level of administration within Sparkfly Loyalty is called a Program. A Program represents the complete ecosystem surrounding a digital loyalty currency, referred to hereinafter as Points. It specifies how/when they are earned (Point Accrual Rules), what Rewards they can be redeemed for, and who is eligible to earn and spend them (aka Enrollments).
Normally, an Account will only set up one Loyalty Program, but there is no limit on this. If there is a need for a user to support multiple loyalty currencies (Points, Cash, Bucks, Miles, etc.), each one would be managed under a separately created Program.
Enrollments
An Enrollment represents a customer's enrollment in a Loyalty Program. To create an Enrollment, a Sparkfly Member, which would be created through the Sparkfly Offer Platform, is required for each customer.
Enrollments manage two things: Point Balances and Reward States (Rewards that have been issued to an Enrollment in exchange for Points). An Enrollment may be referred to as a "Member Wallet" in reference to the latter Reward capability. Activities are logged whenever anything happens within an Enrollment, providing historical data on earned, spent, or expired Points, Reward purchases/redemptions, etc.
Point Accrual Rules
Point Accrual Rules determine how and when monetary transactions earn Points within a Program. The number of points credited to an Enrollment for a transaction can either be a fixed value (e.g. 100 points per visit), proportional to the spend amount (e.g. 5 points per dollar), or a combination of both.
There may situations where a Rule should only be active on certain days, between certain times, and/or on certain day, month, and/or year spans (for example, the first day of every month). This can be accomplished by including a Time Selector (see API docs for more details) when first creating or updating a Rule. When calculating how many points will or would be earned for a transaction, the supplied transaction time will be cross referenced with this Time Selector.
For Programs where not all purchasable items should count towards point earning, an item_set_id may be specified on the Rule. Items Item Sets can be created using the Sparkfly Offer Platform.
There is no limit to how many Rules can be created for a Program. Rules operate independently, and any that are valid at the time a transaction is processed will be applied. Standard usage would be to create a "Base Rule" that applies at all times (no Time Selector). If a promotion such as "Double Point Tuesdays" was being ran, an additional Rule could be created with the same earn rate as the base rule, but with a Time Selector that only applies on Tuesdays.
Reward Catalogs
Reward Catalogs are set up at the Program level as containers for Rewards. A Catalog is required to create a Reward.
There is no further guidance on how/why to use Catalogs (may be helpful for UIs, Enrollment tiering, etc.), but if there is no need to categorize Rewards, the user would create a single Catalog to store all Rewards.
Rewards
A Reward is anything that can be purchased by an Enrollment in exchange for Points. There are different types of Rewards. Customers leveraging the Sparkfly Offer Platform can create Rewards that are backed by Sparkfly Offers. Offer Rewards may be Fixed Point, where the point value of the Reward is specified in the Reward itself, or Variable Point, where the user determines how many points to spend when the Reward is purchased. Variable Point Offer Rewards provide a flexible means of allowing users to apply points directly towards the balance of an in-progress Transaction without creating extra "uncatalogued" Rewards on the fly. Rewards may also be Non-Offer, representing merchendise or other deliverables outside the Sparkfly ecosystem.
Reward States
A Reward State is a Reward that has been issued to an Enrollment.
Tiering
In normal Programs, all configured Point Accrual Rules and Reward Catalogs will be available to all Enrollments. When using Tiering, however, Point Accrual Rules are configured for each individual Tier, allowing Enrollments’ earn rates to be customized based on their Tier. Reward Catalogs may also be optionally assigned to a specific Tier to limit availability, but are otherwise available to all Enrollments.
Tiers
Once a Tier System Configuration has been defined for a Program, any number of Tiers can be created. Which Tier is the "highest" is notably determined by the order field on the Tier, not how many points are required to earn into it. This is an important distinction.
Tier Grant Rules
Tier Grant Rules, expectedly one per Tier, control if a Tier can be granted and if so how many points an Enrollment must earn accordingly. When determining if an Enrollment has met the criteria to get into a tier, both these rules (which specify how many points) and the Tier System Configuration (which specifies which earned points count towards that) are consulted.
Tier Grants
Tier Grants are what determines which Tier an Enrollment belongs to at any given time. Put simply, Tier Grants are tickets that allow an Enrollment into a specific Tier for a certain amount of time (or indefinitely). These can either be earned when an Enrollment satisfies the conditions of a Tier Grant Rule (called an automatic grant), or assigned through the API (called a manual grant).
When automatic grants expire is determined by the Tier System Configuration (see grant_term_type and grant_term_length fields), while manual grants expire according to a fixed date set through the API.
Enrollments can and likely will accumulate multiple grants as they progress through Tiers, manual grants are assigned, and older grants expire. Even if an Enrollment has already been granted access to a tier, a new grant may be issued in order to extend how long they get to retain access. An Enrollment's Tier is ultimately determined by considering all active Grants, and going off of the highest granted Tier (see note under Tiers above).
New or infrequently transacting Enrollments that don't have any active Grants will automatically have access to the lowest tier configured within a Program by default. This default implicit tier will be represented on the Enrollment but may not ever appear as a Grant; It is not expected for a base/default Tier to have a Tier Grant Rule set up.