The battlepass model
Seasons, tiers, lanes, and the four things that do not work the way they look.
What a battlepass is made of, and the vocabulary the other two pages use.
A battlepass
A ladder of rewards that unlocks as a fan levels up. Your community team builds it in the admin panel, and you render it in your product.
Quests pay per action. A battlepass pays for the total, so the thirtieth quest is still worth doing when the reward on it is small. That is the whole reason to ship one.
Seasons, tiers and the premium track are configured in the Hub. Battlepass in the Hub docs covers that side. This page is about rendering what they built.
Seasons
A season is one run of the ladder. It has a title, a description, optional dates and a status.
| Status | Means | Claims |
|---|---|---|
DRAFT | Not published yet | Closed |
ACTIVE | The current season | Open |
CLOSED | Ended by an admin | Closed |
There is at most one ACTIVE season at a time. Publishing a new one closes the old one.
Tiers
A tier is one rung on the ladder: a level, and what a fan gets for reaching it.
Under the hood, every tier is a quest. Its template is basic.check-level, and the level lives on template.args.level. You will not see these quests in your quest list, because they are filtered out, but they claim through the same reward allocations every other quest does. That is why most of what you already know from Rewards and claims carries straight over.
Levels
A fan's level on the ladder is their community XP level, the same number their profile shows. It is not their membership rank. The two are easy to confuse because a battlepass uses both: XP decides how far up the ladder a fan is, and membership decides which side of it they can claim.
Lanes
A season can have more than one track. There is always a free lane, and there is one paid lane for each membership tier that gates a reward.
The SDK turns the tiers into lanes for you: the premium lane on top and the free lane below it. Every lane has one slot per level, so level 5 is always the fifth slot, even in a lane that has nothing at level 5. Rendering a season shows why that matters for your layout.
Membership
The premium lane is what fans pay for. Whether a given fan can claim a premium tier depends on their membership rank against the rank the tier asks for.
The SDK fetches the fan's membership and the community's membership tiers for you, inside the provider. You never fetch them yourself. See Membership for how the same gate works across the store and the newsfeed.
Four things that do not work the way they look
Worth reading before you build anything. Each of them looks like a bug in your code when you hit it.
A tier is just a quest. There is no separate battlepass state machine and no battlepass claim endpoint. Completing a tier is the ordinary quest completion with a different URL, and claiming it is the ordinary reward allocation claim.
A premium tier completed by a free fan fails silently. The platform quietly undoes it and returns success. There is no error to catch. The SDK's gate check is the only signal you get, so you run it before you show a claim button, not after. Completing and claiming covers it.
isEnabled does not mean unlocked. A tier a fan cannot claim still arrives with isEnabled: true. Lock state comes from the membership gate and nowhere else.
Season dates are for display. Nothing enforces them. A season whose end date has passed stays ACTIVE, and keeps paying out, until an admin closes it. Read the status. Never compute "ended" from the dates, and do not render a countdown that implies the season stops on its own.
No season at all
A community can run a battlepass with no active season. The platform calls this orphan mode: the progress read returns season: null and serves the tiers from the container instead.
That is a supported state, not an error. Render the ladder as normal, and treat claims as open.