📌 Purpose

This recipe helps you set up a points-based loyalty ruleset (scheme) where customers can earn points on purchases, have those points expire after a fixed time, and progress through loyalty tiers based on their engagement. You’ll configure the earn rate, define how long points remain valid, and activate tier tracking—all essential foundations for running a successful earn-based loyalty program.

For more advanced use cases, refer to the full Create Schemes API reference.

🖼 Recipe Overview

By the end of this recipe, you will have created an active loyalty scheme that:

• Allows customers to earn 1 point for every £2 spent
• Enables tiers for customer segmentation or progression tracking
• Automatically expires points 6 months after they’re earned
• Does not allow points to be spent (redeemed) via the Spend API

This setup is ideal for programs where earning is the focus, and points will expire after a given period.

📋 Prerequisites

• Eagle Eye API access
• Client ID and secret for your company unit
• A 3-tier unit structure set up (company > banner > store)
• Defined rules for when and how points should expire
• Defined earn rule for base points

📤 Outputs

Note the following output as your complete your steps for use in future API calls and for validation purposes:

📒 Steps

Step 1: Define Your Scheme Setup

This step defines the rules of your loyalty program: when it starts, how long points are valid, how many points customers earn per spend, and tiers enabled.

• 1.1 A name for your scheme (e.g. Retail Points)
• 1.2 A start and end date (typically long-dated for evergreen programs)
• 1.3 The points expiry rule:
  • Points expire set to 6 months
  • Expiry date is rounded to the end of the month
• 1.4 Select the points expiry rules under services.expiryPoints.rule
• 1.5 Tier tracking enabled: set "tiers": { "enabled": true }
• 1.6 Under rates.earn, name the object using your company unit's incomingIdentifier

Step 2: Call POST /schemes/points

{
	"type": "LOYALTY",
	"accountClientType": "RETAILPOINTS",
	"status": "ACTIVE",
	"class": "POINTS",
	"details": {
		"name": "Fabulous Points",
		"alternativeName": null,
		"description": null,
		"alternativeDescription": null,
		"printerMessage": null,
		"screenMessage": null,
		"startDate": "2025-06-01T00:00:00+00:00",
		"endDate": "2050-12-31T23:59:59+00:00",
		"mode": "OPEN"
	},
	"services": {
		"expiryPoints": {
			"enabled": true,
			"rule": {
				"periodCount": 6,
				"periodType": "MONTH",
				"rounding": "MONTHEND",
				"type": "CUTOFFDATE"
			}
		}
	},
	"rates": {
		"earn": {
			"fabulousinc": {
				"default": {
					"rates": [
						{
							"amount": 1,
							"step": 200
						}
					],
					"type": "STANDARD"
				}
			}
		}
	},
	"tiers": {
		"enabled": true
	}
}

{
	"id": "101139210",
	"type": "LOYALTY",
	"accountClientType": "RETAILPOINTS",
	"status": "ACTIVE",
	"class": "POINTS",
	"reference": "101139210",
	"details": {
		"name": "Fabulous Points",
		"alternativeName": null,
		"description": null,
		"alternativeDescription": null,
		"printerMessage": null,
		"screenMessage": null,
		"tags": null,
		"startDate": "2025-06-01T00:00:00+00:00",
		"endDate": "2050-12-31T23:59:59+00:00",
		"mode": "OPEN"
	},
	"relationships": [],
	"services": {
		"autoTopup": null,
		"credit": null,
		"debit": null,
		"goodwill": null,
		"spend": null,
		"earn": null,
		"exchange": null,
		"gift": null,
		"expiryPoints": null
	},
	"rates": {
		"redemption": null,
		"earn": {
			"fabulousinc": {
				"default": {
					"description": "",
					"name": "",
					"product": null,
					"maximumQuantityPerProduct": null,
					"rates": [
						{
							"bonus": null,
							"ceiling": null,
							"floor": null,
							"amount": 1,
							"step": 200,
							"offset": null
						}
					],
					"type": "STANDARD"
				}
			}
		},
		"burn": null
	},
	"rules": {
		"creation": {
			"schemeLimit": null,
			"consumerLimit": null
		}
	},
	"timeoutOverride": null,
	"custom": null,
	"dateCreated": "2025-06-10T18:47:20+00:00",
	"lastUpdated": "2025-06-10T18:47:20+00:00",
	"tiers": {
		"enabled": true
	},
	"version": 2
}

✅ Business Readiness Checklist

Use these steps to validate the setup of your scheme:

• Confirm the scheme was created using GET /schemes/schemeId

• Validate the start and end dates match your intended program duration

• Confirm that points expiry is enabled and set to 6 months

• Confirm tiers are enabled ("tiers.enabled": true)

• Ensure the earn rate is visible under rates.earn and includes your company's incomingIdentifier

• Create a points account using the schemeId from the response and confirm it returns a successful 201 Created response

🔧 Troubleshooting Tips