Managing Collectibles

What It Is

A collectible is a digital token a customer owns, earned by scanning the authentication code on a physical product. Each collectible has a fixed supply cap and its own artwork.

Customers hold collectibles in the app and can spend them to redeem a collectible campaign.

What You Can Do With It

Prove a customer bought the real thing

Bind a collectible to a product batch. Scanning any auth code in that batch grants it, so the token is evidence the customer had a genuine unit in hand.

Config: create the collectible, set current_supply to the number of units in the batch, bind it to the batch.

Run a "collect the set" promotion

Award different collectibles across several product lines, then create a collectible campaign that consumes them as the entry price for a bigger reward.

Config: one collectible per product line → a collectible campaign whose steps each carry a collectible_id constraint listing what satisfies them. See Creating a Loyalty Campaign.

Reward the earliest buyers differently

Give the first few claimants distinct artwork while everyone after gets the standard piece.

Config: add assets tagged with claim_count 1, 2, 3 for the early claims, plus one untagged asset as the fallback for everyone else.

Gate a limited drop

Cap how many customers can ever hold the token, then use it as the entry condition for an exclusive campaign.

Config: set current_supply to the cap. Claims are refused once it is reached.

Configuration

The collectible

The definition — name, supply and availability.

Field	Purpose
name	Shown to customers and in their transaction history
description	Long-form description
current_supply	The claim cap — see the warning below
max_supply	Ceiling used for planning and display
available	Whether it can currently be claimed
tags	Free-form grouping labels
order	Sort position in the customer app
is_archived	Archived collectibles are excluded from every claim flow

current_supply is a limit, not a count

Despite the name, this is the maximum number of times a collectible may be claimed — not a tally of how many have been. Set it to the total you intend to release.

The artwork

Assets decide what a customer actually receives. On the Nth claim the platform looks for the asset whose claim_count is N, and falls back to the asset with an empty claim_count.

Field	Purpose
collectible_link	The asset granted
bg_asset_link	Optional background artwork
altText	Accessibility text
type	Media type
claim_count	Which claim ordinal this asset is for — empty means fallback

Always define a fallback

A claim that finds no matching asset fails outright. One untagged asset guarantees every customer receives something.

What the customer holds

Field	Purpose
status	pending or approved — only approved counts as owned
asset	The specific artwork granted, resolved at claim time
claim_date	When it was claimed
source	How it was acquired — gift, receipt, transfer or manual

How Customers Acquire Them

Three paths, depending on what the auth code requires.

Path	When it applies	Status
Immediate	Code needs no verification	approved
Held	Code requires age or receipt verification	pending
Released	The pending verification succeeds	→ approved

Every path enforces the same checks: the customer must be identity-verified if the code demands it, each auth code grants its collectible only once, and the claim is refused once current_supply is reached. A held claim reserves nothing — if supply runs out while it is pending, releasing it will still fail.

Admin Actions

Admins can grant or remove a collectible directly, outside any campaign or scan. Both are recorded against the customer with a manual source, so they are distinguishable from scan claims in their history.

Removing a collectible does not restore campaign progress it was spent on.

Setting One Up

1. Products → Collectibles → Create Collectible
2. Set the name, description and supply cap
3. Upload at least one untagged asset; add claim_count-tagged assets for numbered editions
4. Bind it to the product batches whose auth codes should grant it
5. Set available once artwork and bindings are in place

Archive rather than delete when retiring one — existing customer copies survive.

Related Resources

• Creating Products
• Product Batches
• Creating a Loyalty Campaign
• Rewards
• Collectibles on the storefront — how customers hold, use and transfer them