Inventory & fulfillment

When a player wins, the prize becomes an inventory item they own. From there it can be cashed back to balance, shipped as a physical good, or withdrawn for money. 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)
            ├─▶ reserved ─▶ paid_out          (item payout)
            └─▶ 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.
`reserved`	Held for an item payout you are running. Not in the inventory lists; cannot be cashed back, shipped or staked. A release returns it to `unresolved`.
`paid_out`	The item payout was paid. 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 cashback (its percentage of the item’s value, see Cashout) 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).
An order’s items must add up to at least the operator’s shipping minimum (SHIPMENT_BELOW_MINIMUM otherwise); shipping can also be switched off for the operator (SHIPPING_DISABLED). Both are on the operator config. Cashback works for every item either way.
An order’s shipping cost is the shipping cost of its most expensive item (the item’s own, or your default one), charged once per order, not per item. If it is > 0, your wallet is debited first (shipping:player:<hash> idempotency key); a refusal creates no order, and a batch refused after the debit is credited back at once.
Cancelling a pending order refunds the shipping fee the player was charged for it, exactly once, whoever cancels (the player, your desk or the platform’s): a wallet.credit under the shipping:refund:<publicId> key. An order the player was never charged for refunds nothing: one created over S2S (you charge for it on your side, if at all) or goods bought with Nuggets, which ship free.
Orders use opaque public ids (fo_…) and are scoped to the player.

Order statuses

Status	Meaning
`pending`	Placed; the player can still cancel it or change the address.
`processing`, `accepted`, `info_missing`	The operator’s desk is working on it.
`shipped`, `tracking_sent`	On its way.
`delivered`	Delivered. Closed.
`shipped_with_replacements`	The operator sent other items, agreed with the player, instead of the ones ordered. Closed; nothing else changes (no refund, no charge, the ordered items become `fulfilled`).
`cancelled`, `failed`	Closed without shipping.

An order line whose item was out of stock when shipping was requested carries waitingForStock: true; the order’s status is not affected.

Once the order ships, it carries the carrier and trackingNumber your desk entered and, when the desk also entered one, a trackingUrl to the carrier’s tracking page; deliveredAt and replacementsSentAt date the two closing states. See the order shape.

Every change to an order (created, a status move, tracking, address, a cancel, whoever made it) is pushed to your webhook as a fulfillment_notice event, so you can notify the player and update your own records. A cancel’s notice says what the platform refunded the player for shipping: 0 when it charged nothing, so a shipping fee you charged is yours to refund.

Item payout

A player can withdraw items for money through your own withdrawal flow: you quote and reserve the items, pay the player, then confirm (the items become paid_out) or release them (back to unresolved). Reserved and paid-out items leave the inventory lists, as the player follows them on the withdrawal.

Goods bought with Nuggets

Your shop can sell catalog items for Nuggets: you price and sell them, then grant the basket. The goods enter the inventory with the acquisition type bought_with_nuggets and can only be shipped: cashback, the item payout and an Upgrader stake refuse them. While shipping is on they go straight into a shipping order to the player’s address; while it is off they wait in the inventory, unresolved, until the player ships them. The same item won from a box is an ordinary item.

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.

Nuggets prizes

A Nuggets prize (item type nuggets) is worth a value in the player’s currency, never a number of Nuggets: you turn that value into Nuggets at your own rate. When a player wins one, nothing enters their inventory and no webhook of its own is sent. The round’s facts carry itemType: "nuggets" and itemValueMinor for the reel, and you credit the player’s Nuggets from those. So a Nuggets prize can never be cashed back, shipped, paid out or staked, and the Upgrader never offers it as a target.

The prize’s name is generic (“Nuggets”) and its image carries no number, so a change of your rate needs no edit to the item. To show the amount, compute it from the prize’s value and your rate wherever you show the prize. The game app does the same when you pass your rate at launch (nuggetsRate). Without it, the prize reads “Nuggets worth $25.00”. Its name shows in the Nuggets colour set under Integration → Iframe.