# 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.

| Tier | Example Name | Example Multiplier |
| ---- | ------------ | ------------------ |
| 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](https://github.com/Spree-Finance/spree-docs/blob/main/products/boost-engine/README.md) reads each user's tier and applies the corresponding multiplier to campaign rewards.

For technical integration details, see [SDK Reference](https://github.com/Spree-Finance/spree-docs/blob/main/developer-guides/stable-points-sp/sdk-reference/README.md) (SpreeStatusRegistry wrapper).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://spree-finance.gitbook.io/spreefinance/products/status-tiers.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.