Management Tooling - Loyalty Schemes

There are two main parts of managing loyalty schemes: the loyalty scheme itself and discounts to accrue/spend points.

Make sure you've read the Loyalty Schemes overview guide before reading this guide.

The Loyalty section of the tooling is where you can setup and manage loyalty schemes:

Prerequisites

Before setting up a loyalty scheme you need to know what the unique identifier in the scheme is going to be and you need to have created a property for this.

For example, if the loyalty scheme is card based you need to create a property for the card number. If your loyalty scheme is a user based scheme then you will need some unique user ID property (e.g. a UUID for each customer).

The property then needs to be populated when calling the Processor API evaluation endpoint.

Creating a Scheme

As an example, let's setup a customer based loyalty scheme. This relies on a unique customer identifier to identify entries in the scheme.

In the Admin - Properties section, we have created a User ID property:

Now click the "Add Loyalty Scheme" button on the loyalty scheme listing page. We can then choose the User ID property as the Scheme Entry Property:

The "Enabled" checkbox can be used to disable a scheme. This will stop any points being accrued or spent by any discounts setup for the scheme.

Click the "Add" button to setup tiers for the loyalty scheme:

As the text on the page describes, these can be used to target different groups of customers (see the Discounts section below).

Note when a loyalty scheme is created, a number of properties are created under an object with the loyalty scheme name:

Active in scheme - boolean value that is true if the customer is already enrolled in the loyalty scheme (i.e. they have an entry)
Balance - number value containing the customer's points balance
Tiers - multivalued string value containing the customers loyalty scheme tiers (based on their points balance)

These properties can be used on discount conditions or action tiers. See Discounts below.

Managing a Scheme

On the loyalty scheme listing page, click on the scheme you want to manage. For a new scheme this won't have any data yet:

Entries can be added to a scheme in a number of ways:

Setting up discounts to accrue points (see Discounts below)
Click the "Create New Entry" button to add an entry using the tooling
Using the Builder API to create entries (e.g. by integrating with your customer management system)

Once a loyalty scheme has entries, you can look these up. The example below uses the user UUID User ID property we created above.

The Staging instance of a loyalty scheme can be used with staged discounts to test a loyalty scheme before making it available to customers. For example, you can setup a loyalty scheme and create a discount to accrue points in a status of Staged. When you have tested the discount you can view the points balance using the "Staging" option.

Scheme Statistics

A number of statistics are calculated for each scheme (these are calculated on a schedule). These are:

Entries - number of entries in the scheme
Total Active Points - the total number of active points that can be spent
Total Points Not Yet Active - the number of points that aren't yet active because they have a start date in the future

Note, these statistics are only calculated for the Live instance of the scheme.

Entry Details

For an entry in the scheme you can see the points balance as well as the transactions (note. transactions are processed asynchronously so they can take a few minutes to appear).

The transactions show you when and how many points were accrued or spent. For an "Increment" transaction any start and expiry dates are displayed.

You can also create a transaction (increment or decrement points) by clicking the "Adjust Balance" button. This opens the "Adjust Balance" sidebar:

Discounts

There are currently 3 discount actions that can be used for loyalty schemes:

Accrue Loyalty Points
Pay With Loyalty Points
Redeem Loyalty Points

These are described below.

Note. if a loyalty scheme is disabled these actions won't do anything.

Accrue Loyalty Points

To allow customers to earn points you can use the "Accrue Loyalty Points" action on a discount. Below is an example of the action sidebar.

Below are details on the options available on the "Accrue Loyalty Points" action sidebar.

Loyalty Scheme - the scheme this action uses
Calculator Type - "Ratio" or "Fixed"
- "Ratio" - you specify the value as a ratio from the currency amount spent to the number of points earned.
- "Fixed" - you specify the value as a fixed number of points.
Ratio Target - if the Calculator Type is "Ratio" then you have the option between "Basket" and "Evaluator" to get the currency value.
- "Basket" - uses the Total property from the Basket object. This is the current discounted total of the line items
- "Evaluator" - uses the Total property from the Evaluator object. This is the current discounted total including basket and costs.
Points Start - when the points should be activated. Either "Relative" or "Absolute".
- "Relative" - relative from when the points were earned. You can specify values in days or months.
- "Absolute" - a specific date (e.g. midnight 25 December 2024)
Points Expiry - when the points should no longer be active (same options as start date)

Automatic Enrolment

For a "Accrue Loyalty Points" action you can choose if you want a customer to be automatically enrolled in the scheme or if they need to be added to the scheme before they can earn points.

For example, schemes based on a card number may allow automatic enrolment because all that is required is that the customer has the card number. However, schemes based on a user may require users to be enrolled before they can earn points.

To ensure only users who are already enrolled can earn points, add an eligibility expression using the "Active in Scheme" property::

Tiers

If you want to vary the amount of points given to different customers you can use action tiers. See Discount Actions for more info on tiers.

You can use the loyalty scheme tiers as conditions for the action tiers. E.g. the condition below matches customers in the "Gold" loyalty scheme tier:

You can then setup different values for the tier:

Pay With Loyalty Points

To allow customers to use their points to pay for things you can use the "Pay With Loyalty Points" action on a discount. Below is an example of the action sidebar.

This action uses a ratio between the number of points and the currency value. E.g. a ratio of GBP 0.01 would take £1 off for every 100 points.

So if the customer has a balance of 5000 points and they are spending 60 GBP, they will get a reduction of 50 GBP (5000 * 0.01) and only pay 10 GBP.

Below are details on the options available on the "Pay With Loyalty Points" action.

Loyalty Scheme - the scheme this action uses
Ratio Target - you have the option between "Basket" and "Evaluator" to get the currency value.
- "Basket" - uses the Total property from the Basket object. This is the current discounted total of the line items
- "Evaluator" - uses the Total property from the Evaluator object. This is the current discounted total including basket and costs.

You can choose if points are spent automatically or if the customer needs to choose to spend them. This is done using a condition on the discount and the information being passed to the evaluation endpoint of the Processor API.

Redeem Loyalty Points

The Redeem Loyalty Points action can be used to redeem a fixed number of points: