📌 Purpose

Your loyalty points rules (scheme) defines how points are tracked and managed across your program. This recipe walks you through setting up a simple scheme focused on points expiry, without configuring how customers earn or redeem points. This structure is often used in reward bank setups or tier tracking programs, where you want to monitor points but control how they're issued separately.

If you are building a more advanced program with earning and redemption rules, refer to the Create Schemes API reference for full configuration options.

🖼 Recipe Overview

You will create a points-based loyalty scheme that sets expiry rules for any points added to a customer’s account. These expiry rules ensure points are automatically removed after a set time window. By the end of this recipe, your scheme will:

• Expire points 12 months after they are added
• Round the expiry date to the end of the month
• Be active and ready to support points accounts

This is a common configuration for loyalty programs that issue points through coupon redemption and want to limit points liability.

📋 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

📤 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

Start by creating the basic configuration for your loyalty scheme. You'll define the name, validity window, and how long points remain active before expiring.

• 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 after 12 months
  • Expiry date is rounded to the end of the month
• 1.4 Select the points expiry rules under services.expiryPoints.rule

Step 2: Call POST /schemes/points

{
	"type": "LOYALTY",
	"accountClientType": "RETAILPOINTS",
	"status": "ACTIVE",
	"class": "POINTS",
	"details": {
		"name": "Retail 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": 12,
				"periodType": "MONTH",
				"rounding": "MONTHEND",
				"type": "CUTOFFDATE"
			}
		}
	}
}

{
	"id": "101161638",
	"type": "LOYALTY",
	"accountClientType": "RETAILPOINTS",
	"status": "ACTIVE",
	"class": "POINTS",
	"reference": "101161638",
	"details": {
		"name": "Retail 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": 12,
				"periodType": "MONTH",
				"rounding": "MONTHEND",
				"type": "CUTOFFDATE"
			}
		}
	},
	"rates": {
		"redemption": null,
		"earn": null,
		"burn": null
	},
	"rules": {
		"creation": {
			"schemeLimit": null,
			"consumerLimit": null
		}
	},
	"timeoutOverride": null,
	"custom": null,
	"dateCreated": "2025-06-18T19:06:43+00:00",
	"lastUpdated": "2025-06-18T19:06:43+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 12 months

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

🔧 Troubleshooting Tips