Inventory & fulfillment

When a player wins, the prize becomes an inventory item they own. From there it can be cashed back to balance or shipped as a physical good. LootBox Solutions tracks the item; your wallet handles the money and your fulfillment handles the goods.

Item states

            ┌─▶ cashed_back        (cashout → wallet credit)
unresolved ─┤
            ├─▶ ship_requested ─▶ fulfilled   (shipping)
            └─▶ expired           (unclaimed past its window)

State	Meaning
unresolved	Just won. The player can cash back or ship. The only non-terminal state.
cashed_back	Converted to wallet balance via cashout. Terminal.
ship_requested	A shipping order was placed; awaiting fulfillment.
fulfilled	Shipped/delivered. Terminal.
expired	Not claimed within its window. Terminal.
forwarded_to_casino	Reserved for bonus-style items handled entirely on your side (audit symmetry). Terminal.

Only an unresolved item can still be cashed back or shipped; every other state is a final disposition.

Cashback

Cashout (S2S) or the player-API cashback credits your wallet for the item’s value and flips it to cashed_back. If the wallet credit fails, the item stays unresolved and the casino’s error code is returned — nothing is lost.

Shipping

For physical prizes, the player places a shipping order with an address and contact:

• Orders are all-or-nothing: any non-shippable item in a batch rejects the whole order (INVENTORY_NOT_SHIPPABLE).
• If shipping cost > 0, your wallet is debited first (shipping:player:<hash> idempotency key); a refusal creates no order.
• Orders use opaque public ids (fo_…) and are scoped to the player.

State changes during fulfillment are pushed to your webhook as fulfillment_notice events, so you can notify the player and update your own records.

Bonus prizes

Bonus-type wins (e.g. free spins) don’t enter inventory — they’re delivered to your system directly as a bonus_entitlement webhook for you to grant. See the event types.