Membership
Free and Premium, the one gate that locks the battlepass, the store, the newsfeed and event joins, and the error you should expect.
What a fan pays for, and the check that decides what they can open. It works the same way in four places, so it gets one page.
Tiers
A community has two membership tiers, set up in the Hub: Free and Premium. Each has a name, a badge and a rank.
Free is rank 1. Every fan who joins the community is on it. Premium is rank 2, and it is the tier fans pay for.
A fan who has not joined the community at all has no tier, and counts as rank 0.
Tiers, prices and what each one unlocks are set in the Hub. The SDK reads membership. It cannot sell or upgrade one: that happens in your product, through your own checkout.
The rule
One comparison, the same one the platform uses:
A fan can open something when their rank is at or above the rank it asks for.
Premium opens everything. Free opens nothing paid. A fan with no membership is below both tiers, and joining the community is what puts them on the free one.
Where it applies
| Feature | What gets locked | How the SDK checks it |
|---|---|---|
| Battlepass | The premium lane | Inside Battlepass.Provider. See Tier states. |
| Store | Members-only listings | Inside Store.Listing, as the first gate reason. See The gate. |
| Newsfeed | Members-only posts | resolveNewsfeedPremiumGate. See The members-only lock. |
| Events | Joining a members-only event | Inside QuestEvent.Provider, as the button's GET_MEMBERSHIP state. See Joining. |
| Leaderboard | Nothing | The board is public. |
In the battlepass, the store and events you never check membership yourself. The provider does it and hands you the answer. The newsfeed has no provider, so you call the gate on each post.
Premium lane, level 4: Loot box๐ For Premium members
Signed away shirt๐ For Premium members
Behind the scenes: training camp๐ For Premium members
Name the tier
Every gate that locks something tells you which tier would unlock it, by name:
reason.requiredTierName // "Premium"Use it rather than hardcoding the word. The name is set in the Hub, so a community can call its paid tier whatever suits its fans, and "For Premium members" stays right when it is renamed.
Reading it yourself
For anything those features do not cover, like a members-only page of your own:
import {
getMembershipRequirement,
resolveMembershipGate,
useMembership,
useMembershipTiers,
} from '@xborglabs/fanbase-react'
const { data: tiers = [] } = useMembershipTiers()
const { data: membership } = useMembership()
const required = getMembershipRequirement(item.requirements) // { tierId } or null
const gate = required
? resolveMembershipGate({ requiredTierId: required.tierId, tiers, membership })
: null
// gate.locked, gate.requiredTier, gate.reason.requiredTierNameNo communityId anywhere. Both hooks resolve it from the slug on FanbaseProvider.
useMembership().data also carries the fan's userId, but do not rely on it for identity: it is missing for exactly the fans who have not joined. useViewer names every signed-in fan, member or not.
The error to expect
Worth reading twice.
For a fan who has not joined the community, the membership read fails with a server error rather than returning nothing. The SDK does not retry it and does not hide it, because a real outage looks identical.
So an error from useMembership is normal, and it usually means "not a member". Do not show an error screen for it. Treat it as rank 0: pass membership: undefined to the gate, which locks everything paid, and offer the fan a way to join.
const { data: membership, isError } = useMembership()
// isError here most often means "not a member yet", not "something broke"
const gate = resolveMembershipGate({ requiredTierId: required.tierId, tiers, membership: isError ? undefined : membership })The providers already do this. It only matters when you read membership yourself.
Joining comes first
A fan who has not joined the community gets a different reason from the quest machine, COMMUNITY_GUEST, and it takes priority over a membership lock. That is the right order: joining is the step that puts them on the free tier, so it is the first thing to ask for.
XP is not membership
Two numbers on a fan look like rank and are unrelated. Membership rank is whether they are Free or Premium. Their XP level is how much they have earned. A brand new Premium member can be level 1, and a free fan can be level 40.
The fan's XP comes from useCommunityXP. It drives the battlepass ladder and any XP bar in your product. The leaderboard model lists all four numbers that get called rank.
Checklist
- Every lock names the tier that would open it
- A fan with no membership sees paid content locked, not an error
- An error from
useMembershipleads to a join prompt, not an error screen - A Premium fan opens everything a free fan does
- XP bars read
useCommunityXP, never membership rank