📌 Purpose

Loyalty tiers are a strategic way to reward long-term customer engagement and drive increased spend over time. This recipe outlines how to configure a three-tier structure of Bronze, Silver, and Gold, using Eagle Eye's Tiers API. Each tier can include unique points earning rates, qualification thresholds, and expiry rules. For additional configuration details, refer to the Create Tiers API reference.

🖼 Recipe Overview

What you will build: A fully configured, points-based tier structure synced to a loyalty scheme:

Bronze Tier (Default): 1 point per £100 spent, with no override
Silver Tier: 2x earn rate, qualifying via points or spend
Gold Tier: 3x earn rate, with clear promotion/demotion paths
All tiers will reset balances and expire membership 6 months after enrollment, rounded to the end of the month

This structure is commonly used to incentivize progression and deepen brand loyalty over time.

📋 Prerequisites

Eagle Eye API credentials (clientId & secret)
An active company unit with tiers enabled along with it's incomingIdentifier
A created loyalty scheme with tiers active
Defined tier reset and expiration logic
Defined promotion and demotion criteria

📤 Outputs

After completing this recipe, capture the following output:

Output Name	Purpose
tierId	Used to configure promotion/demotion and membership logic

📒 Steps

Step 1: Setup the Default Bronze Tier

1.1 Select a name for the default tier
1.2 Enter the schemeId in the details container to establish the tier/scheme relationship. See the full recipe on (creating schemes) as needed.
1.3 Set isDefault as true to indicate this tier level is the default
1.4 Use the promotion.ruleSets.rules object to define the promotion rules
- In this example the customer can either spend £1,000 (100,000 pence) or earn 1,000 points
1.5 In the demotion object, define the balanceResetPeriod and membershipExpiryPeriod
- In this request, each will be set to the last calendar day, six months after the tier membership is created

Step 2: Call POST /tier for the default Bronze Tier

{
	"type": "STANDARD",
	"status": "ACTIVE",
	"details": {
		"name": "Bronze Tier",
		"schemeId": "101139210",
		"isDefault": true
	},
	"settings": {
		"schemeOverrides": {
			"earnRates": null
		},
		"promotion": {
			"promotionTierId": null,
			"ruleSets": [
				{
					"rules": [
						{
							"amount": 100000,
							"balanceType": "SPEND"
						}
					]
				},
				{
					"rules": [
						{
							"amount": 1000,
							"balanceType": "POINTS"
						}
					]
				}
			]
		},
		"demotion": {
			"demotionTierId": null,
			"balanceResetPeriod": {
				"periodOffset": {
					"periodType": "MONTH",
					"periods": 6
				},
				"roundingRule": "endOfMonth"
			},
			"membershipExpiryPeriod": {
				"periodOffset": {
					"periodType": "MONTH",
					"periods": 6
				},
				"roundingRule": "endOfMonth"
			}
		}
	}
}

{
	"id": "480",
	"type": "STANDARD",
	"status": "ACTIVE",
	"reference": null,
	"details": {
		"name": "Bronze Tier",
		"schemeId": "101139210",
		"isDefault": true
	},
	"settings": {
		"schemeOverrides": {
			"earnRates": null
		},
		"promotion": {
			"promotionTierId": null,
			"ruleSets": [
				{
					"rules": [
						{
							"amount": 100000,
							"balanceType": "SPEND"
						}
					]
				},
				{
					"rules": [
						{
							"amount": 1000,
							"balanceType": "POINTS"
						}
					]
				}
			]
		},
		"demotion": {
			"demotionTierId": null,
			"balanceResetPeriod": {
				"periodOffset": {
					"periodType": "MONTH",
					"periods": 6
				},
				"roundingRule": "endOfMonth"
			},
			"membershipExpiryPeriod": {
				"periodOffset": {
					"periodType": "MONTH",
					"periods": 6
				},
				"roundingRule": "endOfMonth"
			}
		}
	},
	"dateCreated": "2025-06-16T17:17:20+00:00",
	"lastUpdated": "2025-06-16T17:17:20+00:00"
}

Step 3: Setup the second-level Silver Tier

3.1 Select a name for the tier
3.2 Enter the same schemeId as in step 2 within the details container
3.3 Set isDefault as false
3.4 Set the second tier's. base earn override in settings.schemeOverrides.earnRate.unitSafeName.default.rates
- In this example the silver tier will earn two points per 100 pence spent in lieu of the default one point per 100 pence in the scheme's base earn rules
3.5 Use the promotion.ruleSets.rules object to define the promotion rules
- In this example the customer can either spend £2,500 (250,000 pence) or earn 2,500 points to promote to the next tier
3.6 In the demotion object, define the balanceResetPeriod and membershipExpiryPeriod
- In this request, each will be set to the last calendar day, six months after the tier membership is created

Step 4: Call POST /tier for the second-level Silver Tier

{
	"type": "STANDARD",
	"status": "ACTIVE",
	"details": {
		"name": "Silver Tier",
		"schemeId": "101139210",
		"isDefault": false
	},
	"settings": {
		"schemeOverrides": {
			"earnRates": {
				"fabulousinc": {
					"default": {
						"rates": [
							{
								"amount": 2,
								"offset": 0,
								"step": 100
							}
						]
					}
				}
			}
		},
		"promotion": {
			"promotionTierId": null,
			"ruleSets": [
				{
					"rules": [
						{
							"amount": 250000,
							"balanceType": "SPEND"
						}
					]
				},
				{
					"rules": [
						{
							"amount": 2500,
							"balanceType": "POINTS"
						}
					]
				}
			]
		},
		"demotion": {
			"demotionTierId": null,
			"balanceResetPeriod": {
				"periodOffset": {
					"periodType": "MONTH",
					"periods": 6
				},
				"roundingRule": "endOfMonth"
			},
			"membershipExpiryPeriod": {
				"periodOffset": {
					"periodType": "MONTH",
					"periods": 6
				},
				"roundingRule": "endOfMonth"
			}
		}
	}
}

{
	"id": "481",
	"type": "STANDARD",
	"status": "ACTIVE",
	"reference": null,
	"details": {
		"name": "Silver Tier",
		"schemeId": "101139210",
		"isDefault": false
	},
	"settings": {
		"schemeOverrides": {
			"earnRates": {
				"fabulousinc": {
					"default": {
						"rates": [
							{
								"amount": 2,
								"offset": 0,
								"step": 100
							}
						]
					}
				}
			}
		},
		"promotion": {
			"promotionTierId": null,
			"ruleSets": [
				{
					"rules": [
						{
							"amount": 250000,
							"balanceType": "SPEND"
						}
					]
				},
				{
					"rules": [
						{
							"amount": 2500,
							"balanceType": "POINTS"
						}
					]
				}
			]
		},
		"demotion": {
			"demotionTierId": null,
			"balanceResetPeriod": {
				"periodOffset": {
					"periodType": "MONTH",
					"periods": 6
				},
				"roundingRule": "endOfMonth"
			},
			"membershipExpiryPeriod": {
				"periodOffset": {
					"periodType": "MONTH",
					"periods": 6
				},
				"roundingRule": "endOfMonth"
			}
		}
	},
	"dateCreated": "2025-06-16T18:56:46+00:00",
	"lastUpdated": "2025-06-16T18:56:46+00:00"
}

Step 5: Setup the third-level Gold Tier

5.1 Select a name for the tier
5.2 Enter the same schemeId as in step 2 within the details container
5.3 Set isDefault as false
5.4 Set the second tier's. base earn override in settings.schemeOverrides.earnRate.incomingIdentifier.default.rates
- In this example the silver tier will earn three points per 100 pence spent in lieu of the default one point per 100 pence in the scheme's base earn rules
5.5 Use the promotion.ruleSets.rules object to define the promotion rules
- In this example the customer can either spend £5,000 (500,000 pence) or earn 5,000 points to promote to the next tier
5.6 In the demotion object, define the balanceResetPeriod and membershipExpiryPeriod
- In this request, each will be set to the last calendar day, six months after the tier membership is created
5.5 Set the settings.demotion.demotionTierId to the Silver Tier tierId

Step 6: Call POST /tier for the third-level Gold Tier

{
	"type": "STANDARD",
	"status": "ACTIVE",
	"details": {
		"name": "Gold Tier",
		"schemeId": "101139210",
		"isDefault": false
	},
	"settings": {
		"schemeOverrides": {
			"earnRates": {
				"fabulousinc": {
					"default": {
						"rates": [
							{
								"amount": 3,
								"offset": 0,
								"step": 100
							}
						]
					}
				}
			}
		},
		"promotion": {
			"promotionTierId": null,
			"ruleSets": [
				{
					"rules": [
						{
							"amount": 500000,
							"balanceType": "SPEND"
						}
					]
				},
				{
					"rules": [
						{
							"amount": 5000,
							"balanceType": "POINTS"
						}
					]
				}
			]
		},
		"demotion": {
			"demotionTierId": "481",
			"balanceResetPeriod": {
				"periodOffset": {
					"periodType": "MONTH",
					"periods": 6
				},
				"roundingRule": "endOfMonth"
			},
			"membershipExpiryPeriod": {
				"periodOffset": {
					"periodType": "MONTH",
					"periods": 6
				},
				"roundingRule": "endOfMonth"
			}
		}
	}
}

{
	"id": "482",
	"type": "STANDARD",
	"status": "ACTIVE",
	"reference": null,
	"details": {
		"name": "Gold Tier",
		"schemeId": "101139210",
		"isDefault": false
	},
	"settings": {
		"schemeOverrides": {
			"earnRates": {
				"fabulousinc": {
					"default": {
						"rates": [
							{
								"amount": 3,
								"offset": 0,
								"step": 100
							}
						]
					}
				}
			}
		},
		"promotion": {
			"promotionTierId": null,
			"ruleSets": [
				{
					"rules": [
						{
							"amount": 500000,
							"balanceType": "SPEND"
						}
					]
				},
				{
					"rules": [
						{
							"amount": 5000,
							"balanceType": "POINTS"
						}
					]
				}
			]
		},
		"demotion": {
			"demotionTierId": "481",
			"balanceResetPeriod": {
				"periodOffset": {
					"periodType": "MONTH",
					"periods": 6
				},
				"roundingRule": "endOfMonth"
			},
			"membershipExpiryPeriod": {
				"periodOffset": {
					"periodType": "MONTH",
					"periods": 6
				},
				"roundingRule": "endOfMonth"
			}
		}
	},
	"dateCreated": "2025-06-16T19:32:45+00:00",
	"lastUpdated": "2025-06-16T19:32:45+00:00"
}

Now that all three tiers are available, the promotion and demotion tierIds can be set. The following steps will set the promotion and/or demotion tier for each tierId.

Step 7: Set the promotion rule for the Bronze Tier

7.1 Using the tierId for the Bronze Tier from the response in step 2, call GET /tier/{tierId}
7.2 Copy the response
7.3 Paste the response in the body of the a PUT /tier/{tierId} call and remove the following objects:
- id
- dateCreated
- lastUpdated
- reference
7.4 Set the settings.promotion.promotionTierId to the Silver Tier tierId

Step 8: Call PUT /tier/{tierId} on the Bronze Tier

{
	"type": "STANDARD",
	"status": "ACTIVE",
	"details": {
		"name": "Bronze Tier",
		"schemeId": "101139210",
		"isDefault": true
	},
	"settings": {
		"schemeOverrides": null,
		"promotion": {
			"promotionTierId": "481",
			"ruleSets": []
		},
		"demotion": {
			"demotionTierId": null,
			"balanceResetPeriod": {
				"periodOffset": {
					"periodType": "MONTH",
					"periods": 6
				},
				"roundingRule": "endOfMonth"
			},
			"membershipExpiryPeriod": {
				"periodOffset": {
					"periodType": "MONTH",
					"periods": 6
				},
				"roundingRule": "endOfMonth"
			}
		}
	}
}

{
	"id": "480",
	"type": "STANDARD",
	"status": "ACTIVE",
	"reference": null,
	"details": {
		"name": "Bronze Tier",
		"schemeId": "101139210",
		"isDefault": true
	},
	"settings": {
		"schemeOverrides": null,
		"promotion": {
			"promotionTierId": "481",
			"ruleSets": []
		},
		"demotion": {
			"demotionTierId": null,
			"balanceResetPeriod": {
				"periodOffset": {
					"periodType": "MONTH",
					"periods": 6
				},
				"roundingRule": "endOfMonth"
			},
			"membershipExpiryPeriod": {
				"periodOffset": {
					"periodType": "MONTH",
					"periods": 6
				},
				"roundingRule": "endOfMonth"
			}
		}
	},
	"dateCreated": "2025-06-16T17:17:20+00:00",
	"lastUpdated": "2025-06-16T20:55:10+00:00"
}

Step 9: Set the demotion and promotion rules for the Silver Tier

9.1 Using the tierId for the Silver Tier from the response in step 4, call GET /tier/{tierId}
9.2 Copy the response
9.3 Paste the response in the body of the a PUT /tier/{tierId} call and remove the following objects:
- id
- dateCreated
- lastUpdated
- reference
9.4 Set the settings.promotion.promotionTierId to the Gold Tier tierId
9.5 Set the settings.demotion.demotionTierId to the Bronze Tier tierId

Step 10: Call PUT /tier/{tierId} on the Silver Tier

{
	"type": "STANDARD",
	"status": "ACTIVE",
	"details": {
		"name": "Silver Tier",
		"schemeId": "101139210",
		"isDefault": false
	},
	"settings": {
		"schemeOverrides": {
			"earnRates": {
				"fabulousinc": {
					"default": {
						"rates": [
							{
								"amount": 2,
								"offset": 0,
								"step": 100
							}
						]
					}
				}
			}
		},
		"promotion": {
			"promotionTierId": "482",
			"ruleSets": [
				{
					"rules": [
						{
							"amount": 250000,
							"balanceType": "SPEND"
						}
					]
				},
				{
					"rules": [
						{
							"amount": 2500,
							"balanceType": "POINTS"
						}
					]
				}
			]
		},
		"demotion": {
			"demotionTierId": "480",
			"balanceResetPeriod": {
				"periodOffset": {
					"periodType": "MONTH",
					"periods": 6
				},
				"roundingRule": "endOfMonth"
			},
			"membershipExpiryPeriod": {
				"periodOffset": {
					"periodType": "MONTH",
					"periods": 6
				},
				"roundingRule": "endOfMonth"
			}
		}
	}
}

{
	"id": "481",
	"type": "STANDARD",
	"status": "ACTIVE",
	"reference": null,
	"details": {
		"name": "Silver Tier",
		"schemeId": "101139210",
		"isDefault": false
	},
	"settings": {
		"schemeOverrides": {
			"earnRates": {
				"purpleco1002": {
					"default": {
						"rates": [
							{
								"amount": 2,
								"offset": 0,
								"step": 100
							}
						]
					}
				}
			}
		},
		"promotion": {
			"promotionTierId": "482",
			"ruleSets": [
				{
					"rules": [
						{
							"amount": 250000,
							"balanceType": "SPEND"
						}
					]
				},
				{
					"rules": [
						{
							"amount": 2500,
							"balanceType": "POINTS"
						}
					]
				}
			]
		},
		"demotion": {
			"demotionTierId": "480",
			"balanceResetPeriod": {
				"periodOffset": {
					"periodType": "MONTH",
					"periods": 6
				},
				"roundingRule": "endOfMonth"
			},
			"membershipExpiryPeriod": {
				"periodOffset": {
					"periodType": "MONTH",
					"periods": 6
				},
				"roundingRule": "endOfMonth"
			}
		}
	},
	"dateCreated": "2025-06-16T18:56:46+00:00",
	"lastUpdated": "2025-06-16T21:03:24+00:00"
}

✅ Business Readiness Checklist

Use these steps to validate the setup of your tiers:

Call GET Tiers to validate the tier structure is setup as expected
Verify the demotion and promotion rules are set for each tier
Confirm the appropriate schemeId is in the details container
Double check for the company incomingIdentifier is present in the settings.schemeOverrides.earnRates for the silver and gold tiers
Create a points account in a wallet and verify a 201 Created response is received. Call GET Tier Membership and verify the response shows a tierMembershipId with an ACTIVE status in the response.

🔧 Troubleshooting Tips

Issue	Possible Cause & Resolution
"Cannot set Tier as default..."	Only one tier can be default. Set isDefault to false for 2nd level or higher tiers.
"Integer value found..."	Ensure promotionTierId and demotionTierId are strings, not integers.
Tier not activating	Confirm both company unit and scheme have tiers enabled. Refer to PATCH Units and PUT Tiers API reference pages as needed.