The below outlines a baseline configuration for a loyalty scheme which can be created via the POST schemes/points API. Refer to the Recipes to see more specific examples of how the most common loyalty schemes are setup using this API.

Base Scheme Create

{
    "type": "LOYALTY",
    "accountClientType": "RETAILPOINTS",
    "status": "ACTIVE",
    "class": "POINTS",
    "details": {
        "name": "Fabulous Points",
        "alternativeName": "",
        "description": "",
        "alternativeDescription": "",
        "printerMessage": "",
        "screenMessage": "",
        "startDate": "2025-01-01T00:00:00+00:00",
        "endDate": "2045-12-31T23:59:00+00:00",
        "mode": "OPEN"
    }
}

{
    "id": "101025493",
    "type": "LOYALTY",
    "accountClientType": "RETAILPOINTS",
    "status": "ACTIVE",
    "class": "POINTS",
    "reference": "101025493",
    "details": {
        "name": "Fabulous Points",
        "alternativeName": "",
        "description": "",
        "alternativeDescription": "",
        "printerMessage": "",
        "screenMessage": "",
        "tags": null,
        "startDate": "2025-01-01T00:00:00+00:00",
        "endDate": "2045-12-31T23:59:00+00:00",
        "mode": "OPEN"
    },
    "relationships": [],
    "services": {
        "autoTopup": null,
        "credit": null,
        "debit": null,
        "goodwill": null,
        "spend": null,
        "earn": null,
        "gift": null,
        "expiryPoints": null
    },
    "rates": {
        "redemption": null,
        "earn": null
    },
    "rules": {
        "creation": {
            "schemeLimit": null,
            "consumerLimit": null
        }
    },
    "timeoutOverride": null,
    "custom": null,
    "dateCreated": "2025-04-29 19:31:45",
    "lastUpdated": "2025-04-29 19:31:45",
    "version": 2
}

Scheme Features

This section will do a deeper dive in the Scheme keys, objects and settings that can help customize your scheme to match the goal of your loyalty programme. Not including the id, the following keys can be added to the request, allowing you to setup additional features.

Keys

Key	Description
id	The scheme's unique identifier
type	The scheme is created with a type of LOYALTY by default
accountClientType	The client defined types that accounts should be created as. These are defined in the unit’s wallet configuration. The default value for schemes is RETAILPOINTS.
status	The scheme is created in the status of ACTIVE by default. A scheme can also be in expired status once the details.endDate is surpassed.
class	The scheme is created with a class of POINTS by default. This is a categorization value for Resource APIs in the AIR system.
reference	An external reference used by a third-party system which will allow them to identify a plan within AIR. This must be unique and cannot be changed once set. If left blank, the schemeId will be set as the reference.
relationships	If schemes are related, relationships can be established in this array of objects. Types of relationships are: AGGREGATE_CHILD - Select a scheme that should become the child scheme, this will create an AGGREGATE_CHILD relationship against the parent scheme Child and parent schemes can be used when there use cases for multiple base earn rates needed in a loyalty programme. When using relationships can allow the total points accumulated can be presented as one balance. There may be a programme where food & beverage earns 1 point per £1 spent but 2 points are earned for every £1 spent on fuel. The schemes can house points that burned together, but earn at different rates.
timeoutOverride	Enable this if the default account lock should be different for accounts related to this scheme. When enabled is set to true, pass in the desired the amount of seconds. The lock timeout is the length of time that points will be locked for before automatically being released. The default timeout is 15 minutes (900 seconds). This feature manage how long points remain locked after a transaction occurs. Locking points for a defined period prevents customers from utilizing the same points account multiple times before the transaction has settled.
version	The scheme is created with a version of 2 by default
tags	One or more tags can be added to help locate a group of schemes or enhance reporting
negativeBalance	Enable if points accounts related to this scheme can go into a negative balance. If enabled, autoTopUpFunds can be selected to determine which transaction types the account can automatically top up to 0 after originally resulting in a negative balance.
autoReduce	A flag denoting if the points limit rule is active or not. If exceed is set to true, a limit can be set as the maximum permissible points balance for points accounts. autoReduceFunds can be selected to determine which transaction types the account will use to reduce the points account balance to the maximum.
pointsLimitPerPeriod	If enabled, rules can be set for limiting points rewarded against a points account per defined period (daily, weekly or monthly).
householdSharing	By enabling household wallets, a hierarchical account structure is established, making points accounts visible to all members within the household during adjudication (i.e. POS Connect wallet open).
rules	rules will contain a creation object showing schemeLimit and consumerLimit. While they default to null, a single wallet can only have one ACTIVE points account per scheme.
earnTransactionLimits	To help control fraud or mitigate earn during a period of time, limits can be set on the number of times a wallet can earn points daily. When enabled, set the number of days from 1 to 99.
tiers	Set this object to true if the loyalty programme will utilise tiers. When enabled the scheme will be available to select on a tiers POST or PUT call.
pendingPoints	Enabling Pending points allows you to specify days, weeks or months that points can be held in a pending state. These points cannot be spent until the pending period has ended. A points limit or monetary spend limit can be set to determine when earned points will be marked as pending.

📘
*These relationships can be used by POS systems (Including POS Connect) to perform actions based on that relationship. For example if a consumer has two points accounts from two related schemes, the POS system could see the relationship and fetch the total points from both to present as one balance to the consumer.

Scheme Details

The details object allows you to pass in general information about the scheme including name and description. The start and end dates will determine when the scheme is active.

Key	Description
name	A friendly name by which a plan can be identified
alternativeName	Optional additional name to further identify the scheme
description	Optional object to provide additional details about the scheme
alternativeDescription	Optional object to expand on the description of the scheme
printerMessage	Optional object to pass a message that can be used when printing information about this scheme
screenMessage	Optional object to pass a message that can be used when displaying information about this scheme
startDate	The timestamp that the scheme will start
endDate	The timestamp when the scheme will end
mode	The scheme is created with a mode of OPEN by default

Expanded Scheme Payload

To illustrate additional features that can be enabled on your scheme, below is an example of a scheme with the following rules:

Maximum current balance in a points account of 10,000,000

    "autoReduce": {
        "exceed": true,
        "limit": 10000000,
        "autoReduceFunds": []
    }

Exchange budgeting enabled, sourcing points from a budget

        "exchange": {
            "enabled": true,
            "defaultFunding": {
                "enabled": true,
                "funds": [
                    {
                        "fundingAccountId": "1211789",
                        "fundingPercentage": 100
                    }
                ]
            },
            "reasons": null,
            "restrictions": []
        }

Maximum of 10,000 points can be earned per month

    "pointsLimitPerPeriod": [
        {
            "active": true,
            "period": "ACCOUNT_POINTS_LIMIT_MONTH",
            "value": 10000
        }
    ]

The scheme can be assigned to a loyalty tier

    "tiers": {
        "enabled": true
    }

Household sharing of the points scheme is available

    "householdSharing": {
        "enabled": true
    }

When 500+ points are earned from a transaction, they will be set to pending for 3 days

    "pendingPoints": {
        "enabled": true,
        "value": "3D",
        "criteria": [
            {
                "type": "points",
                "value": 500
            }
        ]
    }

And a maximum of 5 transactions where points are earned per day is set

    "earnTransactionLimit": {
        "active": true,
        "periodType": "DAY",
        "amount": 5
    }

And the ability to automatically top up a points account balance that goes negative. An event of DEBIT will generate in this example. Additional events that could be triggered include EXCHANGE, REFUND_DEBIT and SPEND.

	"negativeBalance": {
		"enabled": true,
		"autoTopUpFunds": [
			"DEBIT"
		]
	}

Here is the final request payload and response with the above features set:

{
    "type": "LOYALTY",
    "accountClientType": "RETAILPOINTS",
    "status": "ACTIVE",
    "class": "POINTS",
    "details": {
        "name": "Retail Points Expanded",
        "alternativeName": "",
        "description": "",
        "alternativeDescription": "",
        "printerMessage": "",
        "screenMessage": "",
        "tags": null,
        "startDate": "2025-04-17 00:00:00",
        "endDate": "2025-07-05 23:59:00",
        "mode": "OPEN"
    },
    "services": {
        "exchange": {
            "enabled": true,
            "defaultFunding": {
                "enabled": true,
                "funds": [
                    {
                        "fundingAccountId": "1211789",
                        "fundingPercentage": 100
                    }
                ]
            },
            "reasons": null,
            "restrictions": []
        },
        "gift": null,
        "expiryPoints": {
            "enabled": false
        }
    },
    "autoReduce": {
        "exceed": true,
        "limit": 10000000,
        "autoReduceFunds": []
    },
    "pointsLimitPerPeriod": [
        {
            "active": true,
            "period": "ACCOUNT_POINTS_LIMIT_MONTH",
            "value": 10000
        }
    ],
    "householdSharing": {
        "enabled": true
    },
    "tiers": {
        "enabled": true
    },
    "pendingPoints": {
        "enabled": true,
        "value": "3D",
        "criteria": [
            {
                "type": "points",
                "value": 500
            }
        ]
    },
  	"negativeBalance": {
		"enabled": true,
		"autoTopUpFunds": [
			"DEBIT"
		]
	},
    "earnTransactionLimit": {
        "active": true,
        "periodType": "DAY",
        "amount": 5
    }
}

{
	"id": "101125482",
	"type": "LOYALTY",
	"accountClientType": "RETAILPOINTS",
	"status": "ACTIVE",
	"class": "POINTS",
	"reference": "101125482",
	"details": {
		"name": "Retail Points Expanded",
		"alternativeName": "",
		"description": "",
		"alternativeDescription": "",
		"printerMessage": "",
		"screenMessage": "",
		"tags": null,
		"startDate": "2025-04-17T00:00:00+00:00",
		"endDate": "2025-07-05T23:59:00+00:00",
		"mode": "OPEN"
	},
	"relationships": [],
	"services": {
		"autoTopup": null,
		"credit": null,
		"debit": {
			"enabled": false,
			"defaultFunding": null,
			"reasons": null,
			"restrictions": []
		},
		"goodwill": null,
		"spend": null,
		"earn": null,
		"exchange": {
			"enabled": true,
			"defaultFunding": {
				"enabled": true,
				"funds": [
					{
						"fundingAccountId": "1211789",
						"fundingPercentage": 100
					}
				]
			},
			"reasons": null,
			"restrictions": []
		},
		"gift": null,
		"expiryPoints": null
	},
	"rates": {
		"redemption": null,
		"earn": null,
		"burn": null
	},
	"rules": {
		"creation": {
			"schemeLimit": null,
			"consumerLimit": null
		}
	},
	"timeoutOverride": null,
	"custom": null,
	"negativeBalance": {
		"enabled": true,
		"autoTopUpFunds": [
			"DEBIT"
		]
	},
	"dateCreated": "2025-06-05T18:24:40+00:00",
	"lastUpdated": "2025-06-05T18:24:40+00:00",
	"autoReduce": {
		"exceed": true,
		"limit": 10000000,
		"autoReduceFunds": []
	},
	"pointsLimitPerPeriod": [
		{
			"active": true,
			"period": "ACCOUNT_POINTS_LIMIT_MONTH",
			"value": 10000
		}
	],
	"householdSharing": {
		"enabled": true
	},
	"tiers": {
		"enabled": true
	},
	"pendingPoints": {
		"enabled": true,
		"value": "3D",
		"criteria": [
			{
				"type": "points",
				"value": 500
			}
		]
	},
	"earnTransactionLimit": {
		"active": true,
		"periodType": "DAY",
		"amount": 5
	},
	"version": 2
}