Stock

Every listing has exactly one stock policy, set in its stock field when you create or edit it.

Stock is claimed inside the purchase transaction with a conditional write, so two players can never both take the last unit. When a published listing's last unit goes, Tanitar publishes shop.stock.depleted, and the listing shows availability: "sold-out" to players until you add more. A purchase that finds no stock is refused with SHOP_SOLD_OUT.

Reversing or cancelling an order does not put its units back. If you want a unit back on sale, add it yourself as described below.

Counted stockCopy Anchor Link

A counted listing carries the number of units it has left:

{ "stock": { "policy": "counted", "remaining": 250 } }

To top it up, read the listing (GET /v1/shop/listings/:listingKey), then edit it with the new number of units left in remaining and the count you read in expectedRemaining:

curl -X PATCH "$REWARD_API_URL/v1/shop/listings/gold-frame" \
  -H "Authorization: Bearer $TANITAR_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "stock": { "policy": "counted", "remaining": 500, "expectedRemaining": 250 } }'

expectedRemaining is what keeps a sale from being lost. Players keep buying while you edit, and remaining is an absolute count, so the service compares the two values you send:

• If remaining equals expectedRemaining, you did not change the count. The edit leaves the stored count alone, so units sold since your read stay sold. Send this when you edit a counted listing for any other reason.
• If they differ, the edit sets the new count only while the stored count still equals expectedRemaining. If a unit sold in between, the edit is refused with 409 SHOP_STOCK_CONFLICT and nothing changes. Read the listing again and resend with the count you now see.

Every edit that sends a counted stock for a listing that is already counted must include expectedRemaining; without it the edit is refused with 422 SHOP_LISTING_INVALID. Leave it out when the listing is not counted yet, including when the edit switches it to counted, and when you switch a counted listing to another policy. An edit that omits stock entirely leaves the count untouched. On a published listing the edit emits shop.listing.published with the new stock.

Code poolsCopy Anchor Link

A code listing sells codes you supply: gift-card codes, game keys, voucher codes. You load them in batches with POST /v1/shop/listings/:listingKey/stock/codes (scope shop:mutate, Idempotency-Key required):

curl -X POST "$REWARD_API_URL/v1/shop/listings/steam-key-10/stock/codes" \
  -H "Authorization: Bearer $TANITAR_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "codes": ["AAAA-BBBB-CCCC", "DDDD-EEEE-FFFF", "GGGG-HHHH-IIII"] }'

{ "listingKey": "steam-key-10", "loaded": 3, "alreadyPresent": 0, "remaining": 3 }

You can load codes into a draft listing before you publish it, and top up a published one at any time.

How codes are protectedCopy Anchor Link

• Each code is encrypted individually before it is stored. The load response contains only counts, never a code.
• No catalog read, order read, event or webhook contains a code. An order reports only how many codes it took (codeCount).
• A code is decrypted only when the buyer re-reads their own order's codes, or when someone holding the separate shop:disclose-code scope discloses it with a reason, which is audited first. See Code disclosure.
• shop:mutate lets a key load codes but never read one back.

RefusalsCopy Anchor Link