📌 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 and define how long points remain valid—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
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
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:

Output Name	Purpose
schemeId	Unique identifier for your loyalty scheme, used when creating points accounts in customer wallets

📒 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 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"
				}
			}
		}
	}
}

{
	"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": {
			"enabled": true,
			"rule": {
				"periodCount": 6,
				"periodType": "MONTH",
				"rounding": "MONTHEND",
				"type": "CUTOFFDATE"
			}
		}
	},
	"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",
	"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
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

Issue	Possible Cause & Resolution
400 Bad Request error	Ensure all required fields are included — optional fields like description and alternativeDescription must still be present, even if set to null.
Missing expiry configuration	Double-check that services.expiryPoints is enabled and the expiry rule is correctly structured.
Points expiry not set	Confirm the rule type is set to CUTOFFDATE with periodCount: 6 and rounding: MONTHEND.