The store model
Listings, prices, the purchase gate, and what a fan actually gets.
What the store is made of, and the vocabulary the other two pages use.
A store
Somewhere fans spend what they earn. Your community team lists items in the admin panel, and you render the storefront in your product, in your design.
If your community runs a spendable currency, give it somewhere to go. Fans notice within about a week whether their balance buys anything.
Listings, prices, stock and the Shopify connection are set up in the Hub. Store in the Hub docs covers that side.
Listings
A listing is one thing on sale. Two ids matter, and they are not interchangeable:
| Id | What it identifies | Use it for |
|---|---|---|
storeItemId | The product | React keys, links, "similar items" |
listingId | One price for that product | Buying |
A product can be on sale for more than one price, so it has one storeItemId and a listingId per price. You always buy a listingId.
Prices never change in place. When your community team changes a price, the platform creates a new listingId. So never cache a price against a storeItemId: the product is the same, the price is not.
What a fan can buy
Every listing is one of four types. The SDK works out which from the listing and gives it to you as listing.type.
type | What the fan gets |
|---|---|
prize | A physical or digital prize, often shipped |
inventoryItem | An item that lands straight in their inventory |
lootbox | A loot box, with a reveal |
personalization | A cosmetic, like a border or a badge, that they can equip |
The type decides what happens after the purchase, which is why Buying branches on it.
Prices and currencies
A listing is priced in a spendable resource, and a community can have more than one: Credits, Coins, whatever your team called them. A single product can even be priced in two.
So a price is a number and a unit, never a number alone. Show 12 Credits, not 12. The SDK builds that label for you, including for fans who are not signed in, and Browsing shows how.
For the same reason, a fan's balance is a list, not a number. Always read the balance of the currency the listing is priced in.
The purchase gate
Before a fan can buy something, four things have to be true. The SDK checks them in this order, before any request, and reports the first one that fails:
| Reason | Means |
|---|---|
MEMBERSHIP_REQUIRED | The listing is for a membership tier above the fan's |
OUT_OF_STOCK | None left |
REQUIREMENTS_MISSING | The listing needs details the fan has not given yet, like a shipping address |
INSUFFICIENT_BALANCE | They cannot afford it |
You render the reason. You do not work it out. Buying covers each one.
The gate exists because the platform is unhelpful when a purchase is refused. A fan below the right membership tier gets the same generic error as a fan who typed their email wrong. A reason you can show is always cheaper than a failure you have to decode.
Premium items are visible to everyone
Listings are public and unfiltered. Every fan sees every item, including the ones only members can buy, and the platform only refuses at the moment of purchase.
That is deliberate. A locked item stays visible so fans can see what membership gets them. The gate tells you which tier unlocks it, by name, so you can say "for Premium members" in the community's own words rather than a vague "locked". Membership covers how the same gate works across the battlepass and the newsfeed.
Stock
Stock is checked twice, and you can only see one of the checks.
The first is currentSupply on the listing, which the gate reads. -1 means unlimited, 0 means sold out.
The second is a community-wide limit, checked at the moment of purchase, for prizes and inventory items. It is not on the listing. So a listing that shows stock can still fail with SupplyDepletedError, and your checkout has to handle it even when the card said there were some left.
Spending, not earning
Buying in the store spends points. It never earns them. Fans earn from quests, events and the battlepass, and from buying in your Shopify store when a reward rule matches. If what you want is to reward a purchase, that is Purchase rewards, and there is no buy button involved.
Shopify
When your community connects Shopify in the Hub, some prizes are fulfilled as real Shopify orders. The order is created a moment after the purchase succeeds, not during it, so the purchase comes back as ALLOCATED.
ALLOCATED is expected, not an error. The fan has bought it and the order is on its way. Show "processing". Buying covers how to follow it.