Status & Tiers
Reward Loyalty, Not Just Activity
The tier system ranks users based on how much SP they hold and for how long. Users who hold more SP for longer periods reach higher tiers. Higher tiers unlock larger reward multipliers, exclusive access, and gated on-chain features.
Status & Tiers is separate from Spree XP. XP tracks engagement and activity. Tiers track economic commitment: real token balance held over real time. Brands can use both systems together or either one independently.
Example Tier Configuration
The table below shows one possible configuration. Tier names, thresholds, holding periods, and multipliers are all customizable per brand. A ticketing company, a DeFi protocol, and a hotel chain will each configure different tier structures that match their business.
0
Bronze
1.0x
1
Silver
1.25x
2
Gold
1.5x
3
Platinum
2.0x
4
Diamond
2.5x
Brands choose how many tiers to use (up to 5), what to call them, what balance thresholds and holding periods to require, and what multiplier each tier receives.
How Tier Progression Works
Tiers are calculated from two factors:
Token balance. How much of the brand's SP the user holds.
Holding duration. How long they've maintained that balance.
The system measures time-weighted average balance (TWAB), not point-in-time snapshots. A user who deposits 10,000 SP the day before a reward distribution does not qualify for a high tier. A user who has held 10,000 SP for 30 days does.
Grace Periods
If a user's balance drops below their tier threshold, they keep their current tier for a configurable grace period (default: 7 days). If they restore their balance before the grace period ends, the countdown resets. If the grace period expires, their tier recalculates.
Status Hooks and On-Chain Gating
Brands can read a user's tier status on-chain to gate access to features and experiences:
Exclusive LP rewards. A DEX restricts boosted liquidity rewards to Gold tier and above.
Gated minting. A brand limits access to a premium NFT drop to Platinum members.
Tiered fee discounts. A lending protocol offers lower borrowing rates for higher tiers.
Priority access. A ticketing platform gives Diamond members first access to presale events.
Any smart contract can query the StatusRegistry to check a user's tier and gate activity based on the result.
Per-Brand Configuration
Each brand operates its own tier namespace with full control over:
Number of tiers and their names
Balance thresholds per tier
Holding period requirements per tier
Boost multipliers per tier
Grace period duration
Tier criteria source (on-chain TWAB data or off-chain oracle for purchase history, event attendance, etc.)
Two brands on Spree can run completely different tier structures without affecting each other.
Integration with Boost Engine
The Boost Engine reads each user's tier and applies the corresponding multiplier to campaign rewards.
For technical integration details, see SDK Reference (SpreeStatusRegistry wrapper).
Last updated