Creating Levels
This guide explains how to configure level systems, define XP earning rules, and set up level progression through the Admin API.
This guide explains how to configure level systems, define XP earning rules, and set up level progression through the Admin API.
Overview
Level configuration involves:
- Setting up XP as a currency (if not already done)
- Creating XP earning rules
- Defining level thresholds
- Configuring level rewards (optional)
All level configuration is done through the Admin API.
Setting Up XP Currency
Before users can earn XP, you need to define XP as a currency in your wallet system.
Endpoint
POST /v1/wallet/currencies?tenant_id=${tenant_id}Example: Experience Points
{
"id": "xp",
"name": "Experience Points",
"symbol": "✨",
"is_spendable": false,
"decimal_places": 0
}Response:
{
"id": "xp",
"tenant_id": "your_tenant",
"name": "Experience Points",
"symbol": "✨",
"is_spendable": false,
"decimal_places": 0,
"active": true,
"created_at": "2026-01-28T10:00:00Z",
"updated_at": "2026-01-28T10:00:00Z"
}Creating XP Earning Rules
XP earning rules automatically grant XP when specific events occur.
Endpoint
POST /v1/wallet/earning-rules?tenant_id=${tenant_id}Example: Match Completion XP
Grant XP based on match performance.
{
"name": "Match Completion XP",
"currency_id": "xp",
"event_type": "match.completed",
"event_filter": null,
"calculation": {
"type": "fixed",
"amount": 50
},
"max_per_event": null,
"max_per_day": 1000,
"max_per_week": 5000,
"priority": 10
}Example: Victory Bonus XP
Grant bonus XP for victories.
{
"name": "Victory Bonus XP",
"currency_id": "xp",
"event_type": "match.completed",
"event_filter": {
"op": "eq",
"field": "attrs.victory",
"value": true
},
"calculation": {
"type": "fixed",
"amount": 100
},
"max_per_event": null,
"max_per_day": null,
"max_per_week": null,
"priority": 15
}Example: Score-Based XP
Grant XP proportional to match score.
{
"name": "Score-Based XP",
"currency_id": "xp",
"event_type": "match.completed",
"event_filter": null,
"calculation": {
"type": "per_unit",
"points": 1,
"per": 10,
"field": "attrs.score"
},
"max_per_event": 500,
"max_per_day": 2000,
"max_per_week": 10000,
"priority": 5
}Defining Level Thresholds
Level thresholds define how much XP is needed for each level. This is typically configured through level definitions.
Endpoint
POST /v1/levels?tenant_id=${tenant_id}Example: Basic Level System
{
"name": "Player Progression",
"description": "Main player level system",
"currency_id": "xp",
"levels": [
{
"level": 1,
"xp_required": 0,
"name": "Beginner"
},
{
"level": 2,
"xp_required": 100,
"name": "Novice"
},
{
"level": 3,
"xp_required": 300,
"name": "Apprentice"
},
{
"level": 4,
"xp_required": 600,
"name": "Veteran"
},
{
"level": 5,
"xp_required": 1000,
"name": "Expert"
}
]
}Example: Exponential Progression
{
"name": "Advanced Progression",
"description": "Exponential XP requirements",
"currency_id": "xp",
"levels": [
{
"level": 1,
"xp_required": 0,
"name": "Level 1"
},
{
"level": 2,
"xp_required": 100,
"name": "Level 2"
},
{
"level": 3,
"xp_required": 250,
"name": "Level 3"
},
{
"level": 4,
"xp_required": 500,
"name": "Level 4"
},
{
"level": 5,
"xp_required": 1000,
"name": "Level 5"
}
]
}Configuring Level Rewards
Levels can grant rewards when users reach specific levels.
Attaching Reward Configuration
{
"name": "Player Progression",
"description": "Main player level system",
"currency_id": "xp",
"reward_config_id": "level-rewards-config-id",
"levels": [
{
"level": 5,
"xp_required": 1000,
"name": "Expert"
}
]
}The reward configuration defines what rewards are granted at each level. See Reward Configuration for details.
Updating Levels
To update an existing level system:
PUT /v1/levels/{level_id}?tenant_id=${tenant_id}Only include fields you want to update:
{
"name": "Updated Level System Name",
"levels": [
{
"level": 6,
"xp_required": 1500,
"name": "Master"
}
]
}Best Practices
- Start Simple: Begin with a few levels and expand as needed
- Balanced Progression: Make level requirements achievable but meaningful
- XP Sources: Diversify XP sources to keep engagement high
- Daily Caps: Use daily/weekly caps to prevent abuse
- Reward Tiers: Grant meaningful rewards at milestone levels
- Clear Communication: Show users their progress and next level requirements
Next Steps
- Querying Results - Learn how to retrieve level and XP data
- Levels Overview - Understand the levels system
Levels Overview
The Phoenix Levels system provides a progression framework where users advance through levels by earning experience points (XP). Levels create long-term engagement and provide a sense of achievement as users progress.
Querying Results
This guide explains how to retrieve user level information, XP data, and level progression through the Query Gateway.