Create a Loyalty Program
Configure the Stash loyalty program for your webshop — define tiers, milestones, and reward types in Stash Studio, then handle reward delivery through webhooks.
The Stash loyalty program rewards players for webshop purchases. Players earn XP on every transaction, progress through tiers as their balance grows, and claim milestone rewards you configure. Stash tracks XP balances, tier state, and claim history — your backend only needs to handle milestone reward delivery.
How it works
Configure in Stash Studio
Open your webshop in Stash Studio and navigate to the Loyalty section. Complete setup in this order:
Create reward types
A reward type defines a currency or item your backend can grant. Each reward type you create maps to an itemId in the milestone claim payload.
Two bonus categories are supported:
- Loyalty Points — XP-based progression currency tracked by Stash.
- In-Game Currency — any currency, token, or item that your backend grants on receipt.
Create one reward type per distinct reward your program will offer.
Create tiers
Tiers define XP thresholds and earn rates. For each tier, set:
| Field | Description |
|---|---|
| Name | Display name shown to players in the loyalty hub. |
| XP threshold | Cumulative XP required to enter this tier. The first tier must start at 0. |
| Earn rates | XP (or currency) earned per USD of webshop spend, set per reward type. |
| Icon | Required tier icon displayed in the loyalty hub. |
Create tiers in ascending XP order. Configure earn rates for every tier — there are no inherited defaults.
Earn rates apply based on the player's tier at the time of purchase. A player in tier 2 earns at tier 2 rates for that transaction.
Create milestones
Milestones are one-time reward checkpoints within a tier. For each milestone, set:
| Field | Description |
|---|---|
| Name | Display name shown in the loyalty hub. |
| XP threshold | Cumulative XP at which the milestone becomes claimable. Must fall within the tier's XP range. |
| Icon and background image | Required assets for the milestone card in the loyalty hub. |
| Reward amounts | How much of each reward type is granted when the player claims this milestone. |
Each tier must contain at least one milestone.
Publish the program
The program starts in Draft status — no XP is awarded and milestones are not claimable until the program is published.
Before publishing, Studio validates that:
- The program is enabled and has a display name
- At least one reward type, one tier, and one milestone exist
- The first tier starts at 0 XP and all tier thresholds are unique
- Every milestone falls within its tier's XP range and has an icon, background image, and at least one reward amount greater than 0
Click Publish in the Loyalty overview to activate the program.
Once published, tier and milestone structure is locked — XP thresholds, reward assignments, and amounts cannot change, and tiers or milestones cannot be added or deleted. To make structural changes, unpublish first, edit, then republish.
Handle reward delivery
When a player claims a milestone, Stash delivers the reward through one of two mechanisms. Your Stash engineering contact configures this per shop — it is not a Studio toggle:
| Mode | When to use |
|---|---|
| Async webhook | Simple grants where eventual consistency is acceptable. No additional backend endpoint required. |
| Synchronous API | Real-time delivery with immediate confirmation. Requires your backend to implement an API endpoint. |
Webhook payload
When using async webhook delivery, Stash sends a LOYALTY_MILESTONE_CLAIMED event to your configured endpoint.
{
"type": "LOYALTY_MILESTONE_CLAIMED",
"environment": "production",
"shopId": "your-shop-uuid",
"loyaltyMilestoneClaimed": {
"timeMillis": 1748476800000,
"userId": "player_external_account_id",
"milestoneId": "milestone_uuid",
"rewards": [
{
"itemId": "reward_type_id",
"quantity": 500
}
]
}
}Prop
Type
Idempotency
Stash generates a deterministic deduplication ID for each claim event, derived from the player, shop, and milestone. If your endpoint returns a non-2xx response, Stash retries with the same deduplication ID. Make your handler idempotent — check whether a given (userId, milestoneId) pair has already been fulfilled before granting rewards.
For webhook endpoint setup, signature verification, and retry behavior, see Webhooks Overview.
Surface the loyalty hub
Players view their tier status, XP progress, and claimable milestones through the Stash loyalty hub — a hosted UI embedded in your webshop. No additional integration is required for the hub itself.
To deep-link a player directly into the loyalty hub from within your game, call Generate Loyalty URL. This endpoint returns an authenticated URL tied to the player's current session.
How is this guide?