Goods bought with Nuggets

When a player buys goods with Nuggets in your shop, you sell them and take the Nuggets; LootBox Solutions grants the goods. One call grants the whole basket, one of each good, all or nothing:

POST https://{operator}.app.lootboxsolutions.com/api/s2s/goods/grants

LootBox Solutions never learns your prices, your listing or the Nuggets. It checks that every good can be sold and is in stock, and adds each good to the player’s inventory with the acquisition type bought_with_nuggets. Such an entry is ship only: cashout, the item payout and an Upgrader stake refuse it, for good.

What happens next depends on your shipping switch (capabilities.shippingEnabled on /config):

• Shipping on: send the player’s address. The goods go straight into one new shipping order to that address and never sit in the inventory. The order records its shipping cost as for any order (the highest shippingCostMinor among the goods on the item catalog) and charges nothing: the player paid shipping inside your price. The basket must reach the shipping minimum, as any shipping order must.
• Shipping off: send no address. The goods go into the player’s inventory (unresolved), at any value. Once shipping is back on the player ships them like any other item, paying shipping then.

A typical purchase: open a database transaction, take the Nuggets, call this endpoint, and roll the Nuggets back if it refuses. Send an idempotencyKey of your own (for example the purchase id): a call retried after a timeout grants the basket once.

Request

{
  "playerExternalId": "u_8431",
  "idempotencyKey": "nuggets-purchase-5512",
  "itemIds": [906, 911],
  "address": {
    "name": "Ada Lovelace",
    "line1": "12 Analytical Way",
    "line2": null,
    "city": "Austin",
    "region": "TX",
    "postalCode": "78701",
    "country": "US",
    "phone": null
  },
  "contact": { "email": "ada@example.com" }
}

Field	Required	Notes
playerExternalId	✅	Your player id.
idempotencyKey	✅	Your key for this purchase, up to 190 characters. A retry with the same key, player and goods answers the first call’s result (200); the same key for other goods or another player is refused with GOODS_IDEMPOTENCY_CONFLICT.
itemIds	✅	Catalog item ids from the item catalog, each at most once, up to 50.
address	while shipping is on	The same address object as a shipping order. Send it only while shipping is on.
contact.email	with address	The player’s email for the shipment.

Response — 201

{
  "idempotencyKey": "nuggets-purchase-5512",
  "items": [
    {
      "id": 1201,
      "itemId": 906,
      "name": "Logo hoodie",
      "type": "physical",
      "imageUrl": "https://cdn…/items/hoodie-card.png",
      "valueMinor": 4000,
      "currency": "USD",
      "state": "ship_requested",
      "acquisitionType": "bought_with_nuggets",
      "cashbackMinor": null,
      "cashbackUncredited": null,
      "shippable": true,
      "wonAtRoundPublicId": null,
      "createdAt": "2026-09-25T10:00:00Z"
    }
  ],
  "order": { "publicId": "fo_…", "status": "pending", "shippingCostMinor": 1000, "…": "…" }
}

Field	Notes
items	The new inventory entries, one per good, in the inventory row shape.
order	The shipping order the goods went into while shipping was on; null when they went into the inventory.

A retry answered from the first call returns the same body with 200.

Which goods can be sold

A good can be granted when it is an active physical item with a value above zero that is in stock. A digital, bonus or Nuggets item, an item with no value, an item switched off or removed, and a collectible while your collectibles are off are refused, even if asked. Stock is read live, at the moment of the call.

Errors

When a call is refused, nothing was granted: take no Nuggets, or give them back.

{
  "error": {
    "code": "GOODS_OUT_OF_STOCK",
    "message": "These items are out of stock: 911.",
    "itemIds": [911]
  }
}

Code	Status	When
GOODS_ADDRESS_MISMATCH	409	an address came while shipping is off, or none while it is on: shipping was switched on or off since you priced the basket. error.shippingEnabled says which way it is now; reprice and ask the player again
GOODS_NOT_SELLABLE	422	a good cannot be sold; error.itemIds names them
GOODS_OUT_OF_STOCK	409	a good is out of stock; error.itemIds names them
SHIPMENT_BELOW_MINIMUM	422	shipping is on and the goods’ values add up to less than the shipping minimum; error.minimumMinor, error.valueMinor and error.currency say by how much
GOODS_IDEMPOTENCY_CONFLICT	409	the idempotencyKey was already used for other goods or another player