Prizes and inventory

Prizes and details

What a fan has won, the details form a prize can ask for, and a claim that cannot be sent twice.

What a fan owns, and the form that stands between them and a physical prize. Quests, the battlepass, loot boxes and the store all hand out prizes, and they all use what is on this page.

Prizes

A prize is anything your community team gives away: a signed shirt, a code, a meet and greet. Read the prizes in the community:

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

const { data } = usePrizes({ ownedOnly: true, page: 1, limit: 24 })

data?.results.map((prize) => (
  <article key={prize.prizeId} className="your-prize">
    <img src={prize.mediaPath} alt="" />
    <h3>{prize.name}</h3>
  </article>
))

ownedOnly: true narrows it to what this fan has. Leave it off for a showcase of everything on offer. Only published prizes ever come back.

One prize, with the details it asks for, is usePrize(prizeId).

Two things that are not there: an owned prize has no expiry, and there is no "prize history" read in the SDK. Store purchases have their own history. Purchase history.

The details form

Some prizes cannot be sent without something from the fan: an email for a code, an address for merchandise, a wallet address for an on-chain item. Those are the prize's requirements, and the SDK turns them into form fields:

import { getRequirementFields, isSubmissionRequired } from '@xborglabs/fanbase-react'

const fields = prize.requirements
  ?.filter(isSubmissionRequired)
  .flatMap(getRequirementFields)
  .filter((field) => !field.hidden)

fields?.map((field) => (
  <label key={field.name}>
    {field.label}
    <input name={field.name} type={field.type === 'email' ? 'email' : 'text'} required={field.required} />
  </label>
))

A prize can carry five kinds of requirement, and only three ask the fan for anything:

RequirementFields
emailOne email field
addressSeven: three address lines, city, state, country, postal code. Make country a dropdown.
wallet_addressOne field, named walletAddress
membership_tierNone. Checked by the platform. See Membership.
level_checkNone. Checked by the platform.

isSubmissionRequired drops the last two, so your form never renders an empty step for them.

Each field carries its own label, required and hidden, from how your community team set the prize up. Build validation from required. Never render a hidden field.

The form is yours. One screen or one step per requirement are both fine. The SDK ships the fields, not a wizard.

Sending the details

Worth reading twice. The same three answers go to three different endpoints, in three different shapes, depending on how the fan got the prize. Collect them once, then use the builder for the call you are making:

import { toAllocationClaimPayload, toPurchaseRequirementData, toSubmissionData } from '@xborglabs/fanbase-react'

const values = {
  email: { requirementId: emailRequirement.requirementId, data: 'fan@example.com' },
}

toAllocationClaimPayload(values)   // a prize from a quest
toSubmissionData(values)           // a prize won in a loot box
toPurchaseRequirementData(values)  // a prize bought in the store
The fan got it fromBuilderWhere it goes
A quest rewardtoAllocationClaimPayloadclaimPayload on Quest.Provider. Claims that need details.
A loot boxtoSubmissionDataclaimLootbox. When the item needs details.
The storetoPurchaseRequirementDatarequirementData on Store.Checkout. Details a purchase needs.

Never build one by hand. They differ in ways that are easy to miss and hard to debug: the wallet requirement is called wallet_address, but its field is walletAddress, and the recipient name inside an address is kept by the store builder and dropped by the other two.

Details are saved to the fan's profile by default, so they do not type their address twice. That is what shouldSave controls, and it defaults to true. It does not mean "save this form". It means "remember this for every future prize that asks".

Claim states

A prize won in a loot box sometimes needs a second claim, to send those details. Only sometimes. Work out which before you offer it:

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

const { state } = resolvePrizeClaimState({ opening, prize })
StateMeansShow
REQUIREMENTS_REQUIREDThe prize needs details before it can be sentThe form and a claim button
AWAITING_FULFILMENTDetails sent, a person is fulfilling it"Being processed". No retry button.
ALREADY_DISTRIBUTEDThe fan has itDelivered
NOT_OWNEDThe fan does not own thisLocked

Only REQUIREMENTS_REQUIRED allows a claim. claimLootbox checks the state itself and refuses, without sending anything, in every other one.

AWAITING_FULFILMENT waits on a person. Nothing on the platform moves it to delivered on its own, which is exactly why there should be no retry button. A retry cannot speed up someone packing a box.

Errors

The platform is not much help here. Asking to claim something already claimed, or something that does not exist, or something the fan does not own, all come back as the same generic server error. You cannot tell them apart.

So do not try. Keep the failure message generic, and rely on resolvePrizeClaimState to keep the claim from being sent in those cases at all.

ErrorMeans
PrizeRequirementValidationErrorA detail was rejected. The one error that says which field.
PrizeClaimNotAllowedErrorYour code tried to claim outside REQUIREMENTS_REQUIRED. The SDK stopped it before it was sent.
LootboxBatchTooLargeErrorMore than 100 loot boxes asked for in one read

One case worth special-casing: API code 10010 means the email is already used by another account.

Checklist

  • The prize list shows art from mediaPath
  • The form is built from getRequirementFields, with no step for membership or level
  • Hidden fields are never shown
  • Each call uses the builder named for it, and nothing is built by hand
  • A loot box prize offers a claim only in REQUIREMENTS_REQUIRED
  • A prize awaiting fulfilment says so, with no retry
  • Failures show a generic message rather than guessing at a cause

On this page