Orders and fulfilment

An order is created each time one of your players buys something. Orders are placed on the player plane. Your integration reads them, fulfils the ones that need your team and, when necessary, discloses a delivered code or reverses an order.

Order statesCopy Anchor Link

flowchart LR
    purchase([Purchase]) --> settled
    purchase --> awaiting[awaiting-fulfillment]
    purchase --> rejected
    awaiting -->|claim| inprogress[in-progress]
    inprogress -->|fulfillment| fulfilled
    awaiting -->|player cancels| cancelled
    settled -->|reversal| reversed
    awaiting -->|reversal| reversed
    inprogress -->|reversal| reversed
    fulfilled -->|reversal| reversed

Read ordersCopy Anchor Link

Both routes need shop:read.

GET /v1/shop/orders returns the 100 most recent orders, newest first. It takes no pagination parameters. Filter with the optional query parameters status, listingKey and playerId:

curl "$REWARD_API_URL/v1/shop/orders?status=awaiting-fulfillment" \
  -H "Authorization: Bearer $TANITAR_API_KEY"

GET /v1/shop/orders/:orderId returns one order, or 404 SHOP_ORDER_NOT_FOUND.

An order contains:

The price on each line is the price actually charged, pinned at purchase; later edits to the listing do not change it. An order never contains a code.

Fulfil a manual orderCopy Anchor Link

A manual listing is delivered outside Tanitar: a physical item, a service, a credit in another system. Its order waits in awaiting-fulfillment until your team takes it on. Both steps need shop:fulfill and an Idempotency-Key. The actor recorded on the order is the API key (or administrator) that made the call; there is no field to name someone else.

1. Claim the order so nobody else works on it, and so the player can no longer cancel it:

   Copy Text

   curl -X POST "$REWARD_API_URL/v1/shop/orders/ord_123/claim" \
     -H "Authorization: Bearer $TANITAR_API_KEY" \
     -H "Idempotency-Key: $(uuidgen)"

   The order moves to in-progress. A claim by the holder is a replay and returns the order; a claim by anyone else, or a claim that loses a race with the player's cancellation, is refused with 409 SHOP_ORDER_TRANSITION_CONFLICT, whose message names the state the order is actually in.

2. Deliver the item in your own system.

3. Record fulfilment, with an optional note (at most 1000 characters) the player can see:

   Copy Text

   curl -X POST "$REWARD_API_URL/v1/shop/orders/ord_123/fulfillment" \
     -H "Authorization: Bearer $TANITAR_API_KEY" \
     -H "Idempotency-Key: $(uuidgen)" \
     -H "Content-Type: application/json" \
     -d '{ "note": "Shipped with tracking number 1Z999AA10123456784" }'

   The order moves to fulfilled and shop.order.fulfilled is published. Only an in-progress order can be fulfilled. The claim is kept, so if one person claimed and another fulfilled, the order records both.

To automate manual fulfilment, subscribe a webhook endpoint to shop.order.settled, pick out orders whose status is awaiting-fulfillment, and drive the two calls above from your fulfilment system.

Code disclosureCopy Anchor Link

A player can always re-read the codes they bought. Your support team may also need to see one when a player reports that it does not work. This break-glass action has its own scope, shop:disclose-code, which no other scope implies.

curl -X POST "$REWARD_API_URL/v1/shop/orders/ord_456/code-disclosures" \
  -H "Authorization: Bearer $TANITAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Support ticket 88213: player reports the code was already redeemed" }'

{
  "disclosureId": "…",
  "orderId": "ord_456",
  "lines": [
    { "listingKey": "steam-key-10", "codes": [{ "codeId": "code_…", "code": "AAAA-BBBB-CCCC" }] }
  ],
  "disclosedAt": "2026-10-01T09:30:00.000Z"
}

• reason is required, 1 to 1000 characters. A missing or whitespace-only reason is refused with 422 SHOP_REASON_REQUIRED, and nothing is disclosed or audited.
• An audit record naming the caller, the order and the reason is committed before any code is decrypted. disclosureId identifies it, so you can cite it in the support conversation.
• It is a POST so the code never appears in a URL, and the response carries Cache-Control: no-store. It does not use an Idempotency-Key: every call is a separate, separately audited disclosure.
• The response covers every code line of the order. An order answers 404 SHOP_CODE_UNAVAILABLE when it is not a code purchase, is not settled or was already undone.

Treat the response as a secret: do not log it or store it.

What your players doCopy Anchor Link

Players shop through the player plane, authenticated by their player context (see Player identity). Your Player client calls these routes with the short-lived Player token; you do not call them with an API key. Every route takes the player from the context, so no parameter can name another player, and another player's order reads as not found.

Checkout and direct purchase require an Idempotency-Key header, and may carry the total the player expects to pay (expectedTotal, one { currencyKey, amount } per currency). The player's view of an order omits playerId, cartId, the ledger key, and who on your team claimed, fulfilled or reversed it.

A cart holds award and code lines only; a manual listing is refused at add-to-cart with SHOP_MANUAL_NOT_CARTABLE. An award listing is bought one unit at a time, because a player holds an award once (SHOP_AWARD_QUANTITY_UNSUPPORTED).

Purchase refusalsCopy Anchor Link

A refusal caused by the request itself writes nothing:

A refusal caused by the catalog, the stock, the limit or the wallet is a settled rejection: it is answered 422 with the errorCode below and the orderId of the rejected order it created, and it is published as shop.order.settled with the same code as rejection.reasonCode.

Award and grant refusals may also be carried through under their own AWARD_… or GRANT_… codes.

Refusals on your routesCopy Anchor Link