Item payout

An item payout lets a player withdraw won items for money. You run the withdrawal — what each item pays, the review, the KYC check, the payout method and the money itself; LootBox Solutions says which items can go, what each is worth, and marks them used once you have paid. Four calls, all POST:

Call	What it does
`/payouts/quote`	What items are worth; with no items named, every item the player can withdraw
`/payouts/reserve`	Hold items for one withdrawal: they leave the player’s inventory and cannot be cashed back, shipped or staked
`/payouts/confirm`	The withdrawal was paid: the items are paid out, for good
`/payouts/release`	The withdrawal did not happen: the items go back to the player’s inventory, unchanged

A typical withdrawal:

Quote with no items to show the player what they can withdraw and what each item pays, priced from the values the quote reports.
The player picks items; reserve them under your own reference for the withdrawal (for example its id). Open the withdrawal for what the values the reserve answers pay.
When the money is sent, confirm. If the withdrawal is rejected or cancelled, release. To take one item out of a pending withdrawal, release just that item; to add one, reserve it under the same reference.

No wallet call is made by any of the four: the payout’s money never passes through your wallet.credit, and the player’s balance does not change.

Every call is all or nothing: when it is refused, no item has moved.

Which items can be withdrawn

An item can be withdrawn when it is unresolved — owned and not yet cashed back, shipped or staked. So these are never offered and are refused by reserve:

an item in a pending shipping order (ship_requested);
an item already in another withdrawal (reserved), or already paid out (paid_out);
an item cashed back, shipped, staked or otherwise resolved;
an item bought with Nuggets (bought_with_nuggets), which can only be shipped.

The list the quote returns and the items reserve accepts are the same set, so an item you were offered is only refused if something happened to it in between.

What an item is worth

Each item carries two values, in the currency you ask for, converted at the current rate and rounded up in the player’s favour:

originalValueMinor, its value at win time;
currentValueMinor, its value today: for a collectible, its current market price; for any other item, the value at win time again.

What an item pays is your choice, made from these two values. Paying the value at win time is the usual choice. For a collectible whose price moved since it was won, you may instead pay today’s value, or pay one value in money and the difference in Nuggets. For an item won at 100 and now worth 60: 100, or 60 plus Nuggets worth 40, or 60. For an item now worth 140: 100, 140, or 100 plus Nuggets worth 40. Show the player the amount before they submit.

Quote

POST https://{operator}.app.lootboxsolutions.com/api/s2s/payouts/quote

{
  "playerExternalId": "u_8431",
  "inventoryItemIds": [88, 91, 97],
  "currency": "USD"
}

Field	Required	Notes
`playerExternalId`	✅	The player whose items are quoted.
`inventoryItemIds`	—	Up to 100 items. Omit to quote every item the player can withdraw, newest first. When named, every item must be withdrawable or the call is refused.
`currency`	—	ISO 4217 of the player’s wallet. Omit for your operator currency.

Response — `200`

{
  "items": [
    {
      "inventoryItemId": 88,
      "itemId": 412,
      "name": "Wireless Earbuds",
      "type": "physical",
      "imageUrl": "https://…/card.webp",
      "isCollectible": false,
      "wonAt": "2026-09-24T18:02:11+00:00",
      "originalValueMinor": 4000,
      "currentValueMinor": 4000
    },
    { "inventoryItemId": 91, "itemId": 377, "name": "Smart Watch", "type": "physical", "imageUrl": null, "isCollectible": false, "wonAt": "2026-09-21T09:40:00+00:00", "originalValueMinor": 3000, "currentValueMinor": 3000 },
    { "inventoryItemId": 97, "itemId": 205, "name": "Charizard Holo", "type": "physical", "imageUrl": "https://…/card.webp", "isCollectible": true, "wonAt": "2026-08-30T20:15:37+00:00", "originalValueMinor": 2000, "currentValueMinor": 1500 }
  ],
  "totalOriginalValueMinor": 9000,
  "totalCurrentValueMinor": 8500,
  "currency": "USD"
}

Field	Notes
`items[].wonAt`	When the player won the item (ISO 8601), as on the inventory item detail.
`items[].originalValueMinor`	The item’s value at win time.
`items[].currentValueMinor`	The item’s value today; equal to `originalValueMinor` for an item that is not a collectible.
`totalOriginalValueMinor`	The sum of `originalValueMinor`.
`totalCurrentValueMinor`	The sum of `currentValueMinor`.

All amounts are in currency.

A quote holds nothing: the items stay where they are until you reserve them.

Reserve

POST https://{operator}.app.lootboxsolutions.com/api/s2s/payouts/reserve

{
  "playerExternalId": "u_8431",
  "inventoryItemIds": [88, 91, 97],
  "payoutReference": "wd_20931",
  "currency": "USD"
}

Field	Required	Notes
`playerExternalId`	✅	Must own every item.
`inventoryItemIds`	✅	1 to 100 items, each withdrawable (or already reserved under this `payoutReference`).
`payoutReference`	✅	Your reference for the withdrawal, up to 64 characters. `confirm` and `release` act only on items reserved under it.
`currency`	—	As for the quote.

The answer is the quote of the items reserved, with the reference:

{
  "items": [ … ],
  "totalOriginalValueMinor": 9000,
  "totalCurrentValueMinor": 8500,
  "currency": "USD",
  "payoutReference": "wd_20931"
}

Price the withdrawal from these values: they are the values at the moment the items were held, and they are fixed here, so a later price move changes neither a retried reserve nor the confirm. Keep what you priced each item at: the confirm reports the values, not what you paid.

The reserved items move to reserved. From then on they are not in the inventory lists, whatever state filter you ask for, nor in the player summary counts: the player follows them on the withdrawal, not on the item. A cashout of one is refused with CASHBACK_NOT_AVAILABLE, a shipping order with INVENTORY_NOT_SHIPPABLE, and staking it in an Upgrader round with UPGRADER_ITEM_NOT_OWNED.

Retries are safe. An item already reserved under the same payoutReference is accepted again, so a retried reserve succeeds and answers the same values, and a reserve naming more items under the same reference adds them to the withdrawal. An item reserved under another reference is refused.

Confirm

Call it once the money has been sent.

POST https://{operator}.app.lootboxsolutions.com/api/s2s/payouts/confirm

{
  "playerExternalId": "u_8431",
  "inventoryItemIds": [88, 91, 97],
  "payoutReference": "wd_20931"
}

Every item must be reserved under payoutReference, or the call is refused. The items move to paid_out: used up for good, never listed again, and no later call can bring them back. Each item carries its two values, as fixed at the reserve. If you pay part of a withdrawal in Nuggets, book that part now, from what you priced it at.

{
  "items": [
    { "inventoryItemId": 88, "state": "paid_out", "originalValueMinor": 4000, "currentValueMinor": 4000, "currency": "USD" },
    { "inventoryItemId": 91, "state": "paid_out", "originalValueMinor": 3000, "currentValueMinor": 3000, "currency": "USD" },
    { "inventoryItemId": 97, "state": "paid_out", "originalValueMinor": 2000, "currentValueMinor": 1500, "currency": "USD" }
  ],
  "totalOriginalValueMinor": 9000,
  "totalCurrentValueMinor": 8500,
  "currency": "USD"
}

The totals and currency are null if the items were reserved in different currencies; one withdrawal never is.

A retried confirm succeeds and changes nothing.

Release

Call it when the withdrawal is rejected or cancelled, or to take items out of a pending withdrawal. Same body as confirm.

POST https://{operator}.app.lootboxsolutions.com/api/s2s/payouts/release

The items reserved under payoutReference go back to unresolved, with the same value as before: they are in the player’s inventory again and can be cashed back, shipped, staked or withdrawn. An item that is not reserved under the reference is left as it is, so a retried release succeeds; the answer lists the state of every item named.

{
  "items": [
    { "inventoryItemId": 88, "state": "unresolved" },
    { "inventoryItemId": 91, "state": "unresolved" },
    { "inventoryItemId": 97, "state": "unresolved" }
  ]
}

A release naming an item already paid out under the reference is refused: a paid withdrawal cannot be undone.

Errors

Refusals carry the items that caused them in error.inventoryItemIds:

// 422
{
  "error": {
    "code": "PAYOUT_ITEMS_NOT_WITHDRAWABLE",
    "message": "These items cannot be withdrawn: 91.",
    "inventoryItemIds": [91]
  }
}

code	HTTP	when
`PAYOUT_ITEMS_NOT_WITHDRAWABLE`	422	quote or reserve: an item is not the player’s, or cannot be withdrawn
`PAYOUT_ITEMS_NOT_RESERVED`	409	confirm: an item is not reserved under this `payoutReference` for this player
`PAYOUT_ITEMS_PAID_OUT`	409	release: an item was already paid out under this `payoutReference`
`UNSUPPORTED_CURRENCY`	422	the requested `currency` has no configured rate; nothing was reserved
`VALIDATION_ERROR`	422	a required field is missing or malformed