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:
| Requirement | Fields |
|---|---|
email | One email field |
address | Seven: three address lines, city, state, country, postal code. Make country a dropdown. |
wallet_address | One field, named walletAddress |
membership_tier | None. Checked by the platform. See Membership. |
level_check | None. 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 from | Builder | Where it goes |
|---|---|---|
| A quest reward | toAllocationClaimPayload | claimPayload on Quest.Provider. Claims that need details. |
| A loot box | toSubmissionData | claimLootbox. When the item needs details. |
| The store | toPurchaseRequirementData | requirementData 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 })| State | Means | Show |
|---|---|---|
REQUIREMENTS_REQUIRED | The prize needs details before it can be sent | The form and a claim button |
AWAITING_FULFILMENT | Details sent, a person is fulfilling it | "Being processed". No retry button. |
ALREADY_DISTRIBUTED | The fan has it | Delivered |
NOT_OWNED | The fan does not own this | Locked |
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.
| Error | Means |
|---|---|
PrizeRequirementValidationError | A detail was rejected. The one error that says which field. |
PrizeClaimNotAllowedError | Your code tried to claim outside REQUIREMENTS_REQUIRED. The SDK stopped it before it was sent. |
LootboxBatchTooLargeError | More 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