Skip to content

Shipping

The shipping endpoints turn a player’s won physical items into a fulfillment order. Use them when you drive everything from your backend and render your own ship cart / orders surface. Pick shippable items from inventory (shippable: true), then create an order.

LootBox Solutions does not charge for shipping. Creating an order records the request (with a computed shippingCostMinor for reference) and moves the items to ship-requested — it never calls your wallet. You own the wallet, so if you charge for shipping you do it on your side. That’s why every response’s balanceAfterMinor is null.

Create an order

POST https://{operator}.app.lootboxsolutions.com/api/s2s/shipping/orders

{
  "playerExternalId": "u_8431",
  "inventoryItemIds": [88, 91],
  "address": {
    "name": "Ada Lovelace",
    "line1": "12 Analytical Way",
    "line2": null,
    "city": "London",
    "region": "Greater London",
    "postalCode": "EC1A 1BB",
    "country": "GB",
    "phone": null
  },
  "contact": { "email": "ada@example.com" }
}

Field	Required	Notes
`playerExternalId`	✅	Must own every item.
`inventoryItemIds`	✅	1–50 inventory `id`s (from inventory). All must be `unresolved` and shippable, or the whole batch is rejected.
`address.*`	✅	`name`, `line1`, `city`, `region`, `postalCode`, and a 2-letter `country` are required; `line2` + `phone` are optional.
`contact.email`	✅	Where order updates go.

Response — `201`

{
  "order": {
    "publicId": "ord_3f2a…",
    "status": "pending",
    "currency": "EUR",
    "shippingCostMinor": 0,
    "address": { "name": "Ada Lovelace", "line1": "12 Analytical Way", "city": "London", "region": "Greater London", "postalCode": "EC1A 1BB", "country": "GB" },
    "contact": { "email": "ada@example.com" },
    "createdAt": "2026-06-16T12:00:00Z",
    "items": [
      { "inventoryItemId": 88, "itemId": 906, "name": "Golden Sword", "valueMinor": 320, "currency": "EUR" }
    ]
  },
  "balanceAfterMinor": null
}

Field	Notes
`publicId`	The order handle — pass it to the detail endpoint below.
`status`	Order status (`pending`, …).
`shippingCostMinor`, `currency`	The computed cost, in the operator currency, for your reference — LootBox Solutions does not debit it.
`items[]`	One line per shipped item, valued in its own operator `currency`.
`balanceAfterMinor`	Always `null` — shipping never touches the wallet.

List a player’s orders

GET https://{operator}.app.lootboxsolutions.com/api/s2s/shipping/orders?playerExternalId=u_8431

{ "orders": [ { "publicId": "ord_3f2a…", "status": "pending", "…": "…" } ] }

Newest first. Each order has the same shape as the create response’s order.

One order’s detail

GET https://{operator}.app.lootboxsolutions.com/api/s2s/shipping/orders/{publicId}?playerExternalId=u_8431

{ "order": { "publicId": "ord_3f2a…", "status": "pending", "…": "…" } }

Scoped to the player — another player’s publicId returns ORDER_NOT_FOUND.

Errors

code	HTTP	when
`SHIPPING_DISABLED`	403	shipping is turned off for your operator
`INVENTORY_NOT_SHIPPABLE`	422	an item is missing, not owned by the player, not `unresolved`, or not a shippable type — the whole batch is rejected
`ORDER_NOT_FOUND`	404	no order with that `publicId` for this player

A bad signature returns 401; a malformed body returns 422 with the standard { "error": { "code", "message", "fields" } } envelope.

Same data, two callers. The game app drives the equivalent in-iframe ship cart with a session token. These S2S endpoints are the backend-driven equivalent — signed with your API key.