Battlepass

Completing and claiming

One tier, every tier, and the rewards that need the fan before they can pay out.

How a fan takes what they earned. Short on code, because the SDK does most of it, and long on the two ways it goes quietly wrong.

Claiming one tier

Battlepass.Claim is the button. Put it inside Battlepass.Tier and it knows which tier it belongs to.

{canClaim && (
  <Battlepass.Claim asChild>
    <button className="your-button">Claim</button>
  </Battlepass.Claim>
)}

Pressing it completes the tier if it is not complete yet, then claims every reward the tier produced.

Every reward, not the first one. A tier your community team gave two rewards to produces two allocations, and the platform only has an endpoint for claiming one at a time. A claim that handles only the first one leaves the second behind with nothing on screen to say so. The SDK claims each in turn, so use the button, or useBattlepass().actions.claimTier(slot.tier) if you are wiring your own control.

The silent failure

Worth reading twice.

When a free fan completes a premium tier, the platform does not return an error. It quietly reverts the completion and returns success. Your UI shows a claim that worked, and a moment later it has undone itself, with nothing in the response to tell you why.

So the only protection is to not offer the claim in the first place. canClaim already accounts for membership, which is what the example above relies on. If you build your own button instead of reading canClaim, check the tier state before you enable it:

const { slot, canClaim } = useBattlepassTier()

<button disabled={!canClaim}>
  {slot?.state === 'PREMIUM_LOCKED' ? 'Members only' : 'Claim'}
</button>

Never decide from slot.tier.isEnabled. A locked premium tier reports isEnabled: true, and a button bound to it is exactly the claim that fails silently.

Completing without claiming

Rare, but some tiers take a completion input before they pay out. Use the hook:

import { useCompleteTier } from '@xborglabs/fanbase-react'

const { completeTier, pending, error } = useCompleteTier()

await completeTier(questId)                 // no input
await completeTier(questId, { text: 'x' }) // with input

Do not reach for the quest hooks here. A tier is a quest, so submitQuest looks like it should work, but the tier URL is what tells the platform this is a battlepass completion. Send it through the quest endpoint and it is rejected.

Claiming everything

A "claim all" button is worth having. A fan who comes back after a week can have eight tiers waiting.

import { useBattlepass, useClaimAllTiers } from '@xborglabs/fanbase-react'

function ClaimAllButton() {
  const { state } = useBattlepass()
  const { claimAll, pending, results, needsAttention } = useClaimAllTiers(state.claimableSlots)

  const failed = results.filter((result) => !result.ok)

  return (
    <>
      <button onClick={claimAll} disabled={pending}>Claim everything</button>
      {failed.length > 0 && <p>{failed.length} could not be claimed. Try again.</p>}
      {needsAttention.length > 0 && <NeedsYou tiers={needsAttention} />}
    </>
  )
}

Battlepass.ClaimAll is the same thing as a ready-made button, disabled when claims are closed or when there is nothing it can claim on its own.

Tiers claim one after another. If one fails, the rest still go through, and the failure lands in results with its error. The pass refreshes once at the end rather than after every tier.

What claim-all will not claim

Some rewards need the fan in the room, so claim-all leaves them alone and hands them back in needsAttention.

kindWhy it waitsWhat the fan has to do
prizeThe prize asks for details, a shipping address or a sizeFill in the form, then claim
lootboxA loot box has a revealWatch the reveal, then claim if the item won needs details

Everything else settles on its own: currencies, digital assets, Discord roles, personalisation items, and prizes that ask for nothing.

That is a feature. A batch that silently claimed a loot box would skip the reveal, which is the part fans open loot boxes for, and a physical prize claimed with no address cannot ship. Step the fan through each one yourself. Rewards and claims covers the form, and Loot boxes covers the reveal. Both work the same way here as they do for a quest.

Errors

Two are specific to the battlepass. Everything else is the ordinary quest claim error and reads the same way it does there.

ErrorMeans
BattlepassSeasonInvalidTierErrorThe quest is not a tier of this season
BattlepassTierCompleteFailedErrorThe completion failed for a reason the platform did not break out

A premium tier completed by a free fan is not on this list, because it does not raise one. See the silent failure.

After a claim

The pass, your quest list and the fan's inventory all refresh on their own. A tier's rewards are quest rewards, and a tier can grant an item, so the SDK invalidates all three together. You do not need a manual refetch anywhere.

Checklist

  • A tier with two rewards ends with both claimed
  • A premium tier cannot be claimed by a free fan, and the button says why
  • No button is bound to isEnabled
  • Claim-all survives one failing tier and reports it
  • A season mixing currency, prize and loot box tiers claims only the currency tiers, and hands the other two back
  • A loot box tier from needsAttention shows its reveal before anything is claimed

On this page