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

FeatureWhat gets lockedHow the SDK checks it
BattlepassThe premium laneInside Battlepass.Provider. See Tier states.
StoreMembers-only listingsInside Store.Listing, as the first gate reason. See The gate.
NewsfeedMembers-only postsresolveNewsfeedPremiumGate. See The members-only lock.
EventsJoining a members-only eventInside QuestEvent.Provider, as the button's GET_MEMBERSHIP state. See Joining.
LeaderboardNothingThe 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.

One gate, three featuresTry it
The fan
Battlepass
Premium lane, level 4: Loot box
๐Ÿ”’ For Premium members
Store
Signed away shirt
๐Ÿ”’ For Premium members
Newsfeed
Behind the scenes: training camp
๐Ÿ”’ For Premium members
Opens when the fan's rank is at or above the rank it asks for. Free is rank 1. Example data.

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

No 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 useMembership leads to a join prompt, not an error screen
  • A Premium fan opens everything a free fan does
  • XP bars read useCommunityXP, never membership rank

On this page