Tiers
How loyalty tiers work: XP thresholds, the stable string tier ID your backend receives on webhooks, per-tier earn rates, and how tier changes are reported on purchase and refund.
A tier is a named progression level. A player enters a tier when their Loyalty XP crosses the tier's threshold, and holds it as long as their balance stays at or above that threshold. Higher tiers carry more generous earn rates.
Tier IDs
Every tier has a stable string tier ID, set in Studio. This ID is what your backend receives in the loyalty webhook payload; currentTierId, previousTierId, and milestoneTierId all carry it.
Key your logic on the string tier ID, never on the display name. Display names are editable after publish and are localized for players; the tier ID is stable for the life of the campaign.
Thresholds and progression
- The first tier must start at
0XP, so every player begins in a tier. - Thresholds are unique and ascending. A player's tier is the highest tier whose threshold their XP has reached.
- XP is cumulative within a campaign. Reaching a higher tier does not reset the balance.
Because tier is derived from the XP balance, it moves in both directions. A purchase can move a player up a tier; a refund can move them back down when the proportional XP debit drops the balance below a threshold.
Earn rates
Each tier defines an earn rate per USD of webshop spend, for one or more reward types. Earn rates are applied automatically at checkout, using the tier the player is in at the time of purchase.
For example, a Silver tier might grant 10 XP + 5 coins per $1, while Gold grants 20 XP + 10 coins per $1. A player in Silver earns at Silver rates for that transaction, even if the purchase pushes them into Gold.
Tier change reporting
The loyalty webhook payload reports tier transitions explicitly:
currentTierIdis always the player's tier after the event applied.previousTierIdis present only when the event changed the player's tier: an upgrade on purchase or a downgrade on refund. When the tier is unchanged,previousTierIdis omitted.
This lets your backend react to tier changes (for example, unlocking or revoking a tier benefit) without tracking prior state yourself.
Fields
| Field | Type | Required | Notes |
|---|---|---|---|
| Name | Text | Yes | Display name shown in the loyalty hub. |
| Tier ID | Text | Yes | Stable identifier reported on webhooks. Set once. |
| XP threshold | Number ≥ 0 | Yes | First tier must be 0; thresholds unique. Locked after publish. |
| Earn rates | Number > 0 per reward type | Yes | Reward granted per USD spent. Locked after publish. |
| Icon | Image, 162 x 162 px | Yes | Tier badge in the loyalty hub. |
| Background image | Image, 340 x 162 px | No | Banner behind the tier card. |
| Colour | Hex | No | Tier accent colour. |
XP thresholds and earn rates lock when the program is published; display fields stay editable. See Configuration for the publish flow.
How is this guide?
Reward Types
The three reward types a Stash loyalty program grants: Loyalty XP, in-game currency, and catalog products (SKU rewards). Each is defined once in Studio and reused across tiers and milestones.
Milestones & Rewards
One-time loyalty milestone rewards: how the claim flow works, what a milestone reward can contain, and the two delivery modes (async webhook or synchronous API) Stash uses to hand the reward to your backend.