Loyalty Program
Overview of the Stash loyalty program: how programs, campaigns, tiers, milestones, and rewards fit together, and how your backend receives loyalty state on webshop webhooks.
The Stash loyalty program rewards players for webshop spend. Players earn Loyalty XP on every purchase, progress through tiers as their XP grows, and claim milestone rewards you configure. Stash is the source of truth for all program state: XP balances, tier status, and claim history. Your backend only grants the rewards Stash tells it to grant, and receives a consistent view of loyalty state on every XP-affecting webhook.
You configure the program in Stash Studio under the Loyalty section of your shop. It runs on your existing webshop with no additional client integration for accrual.
The model
A shop has one loyalty program. The program is organized as a hierarchy:
| Concept | What it is |
|---|---|
| Program | The loyalty system on your shop. One per shop, configured in Studio. |
| Campaign | A generation of the program, scoped to a season. Every loyalty value your backend receives is stamped with a campaignId so you can reconcile XP and tier across season boundaries. See Refunds & XP adjustments. |
| Reward Type | A reward players can earn, defined once on the Reward Types surface in Studio: Loyalty XP or an in-game currency (Core Currency in Studio). Reward types are applied as per-tier earn rates for spend (reward per USD spent); catalog products can also be granted as milestone rewards. See Reward types. |
| Tier | A named progression level unlocked when the player's XP crosses its threshold. Each tier carries its own spend-based earn rates and contains its own milestones. See Tiers. |
| Milestone | A one-time reward checkpoint at a specific XP value, nested under the tier it belongs to. See Milestones. |
How players earn and claim
Two reward mechanics run in parallel, and the distinction drives the whole integration:
- Accrual is automatic. At checkout, Stash updates the player's Loyalty XP and reports the per-USD Core Currency reward on the purchase webhook for your backend to grant. No player action or extra client integration is involved.
- Milestone claims are player-initiated. When XP crosses a milestone threshold the reward becomes claimable in the loyalty hub. The player clicks Claim, and Stash delivers the reward to your backend to grant.
Loyalty state on webhooks
Every webhook that can change or reflect a player's XP carries a shared loyalty sub-payload (the loyalty snapshot, type PlayerLoyaltyState): the current XP balance, the signed XP delta, the current and previous tier IDs, the current tier's pointsMultiplierPermille (its XP earn rate relative to the base tier, in permille: 2000 = 2x), progress to the next tier and milestone, and the campaignId. It rides on four events:
PURCHASE_SUCCEEDEDPURCHASE_REFUNDEDLOYALTY_MILESTONE_CLAIMEDFREE_ITEM_REDEEMED
Refunds are delivered as genuine XP-update events: Stash debits XP proportional to the refunded amount and reports the new balance and tier. See Analytics & app integration for the full contract.
The same loyalty snapshot is also included in the RegisterPayment and ConfirmPayment purchase requests Stash sends to a real-time-catalog backend, so your backend has the player's tier and XP context in-band at purchase time. See Loyalty snapshot on purchase requests.
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 hub, call Generate authenticated URL from your backend with the target set to LOYALTY. The endpoint returns an authenticated URL that opens the player straight to the loyalty hub.
Next steps
Reward types
Define Loyalty XP, in-game currency, and catalog rewards your program grants.
Tiers
XP thresholds, string tier IDs, and per-tier earn rates.
Milestones & rewards
One-time XP checkpoints, the claim flow, and reward delivery.
Configure in Stash Studio
The end-to-end setup walkthrough, validation, and publishing.
Analytics & app integration
Consume loyalty via webhooks for analytics, and the read-only API for in-app integration.
Refunds & XP adjustments
Proportional refund reversal, tier downgrades, and free-gift XP.
How is this guide?