Listings

A listing is one item in your shop. You create it as a draft, publish it when it is ready, edit it while it is live, and retire it when you stop selling it. All catalog routes need an API key with shop:read (reads) or shop:mutate (writes); every write requires an Idempotency-Key.

LifecycleCopy Anchor Link

Only a draft can be published and only a published listing can be retired; any other transition is refused with 409 SHOP_LISTING_TRANSITION_INVALID. A retired listing cannot be edited or restocked. Orders already placed against a retired listing are unaffected and remain readable.

Every change increments the listing's revision. If two writes race on the same listing, the loser is refused with 409 SHOP_LISTING_REVISION_CONFLICT: read the listing again and retry.

Create a listingCopy Anchor Link

curl -X POST "$REWARD_API_URL/v1/shop/listings" \
  -H "Authorization: Bearer $TANITAR_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "listingKey": "gold-frame",
    "title": "Gold profile frame",
    "description": "A gold frame for your profile picture.",
    "category": "cosmetics",
    "media": "https://cdn.example.com/shop/gold-frame.png",
    "price": [{ "currencyKey": "coins", "amount": "500" }],
    "fulfillment": { "kind": "award", "awardKey": "gold-frame" },
    "stock": { "policy": "counted", "remaining": 1000 },
    "limit": { "maxPerPlayer": 1, "window": "total" }
  }'

The response is the listing as your integration sees it: the authored fields plus status, revision, retiredReason, the computed price legs (base, effective, discount), the current stock.remaining and availability (available or sold-out).

A listing whose fulfilment kind and stock policy do not fit together is refused with 422 SHOP_FULFILLMENT_STOCK_INVALID:

• a code listing must use code-pool, and only a code listing may;
• a counted listing must carry remaining, and the other policies must not;
• an award listing must name an awardKey; code and manual listings must not.

PricesCopy Anchor Link

A price is a list with exactly one leg: one of your currencies and a whole amount in that currency's smallest unit, written as a decimal string ("500"). A second leg is refused with 422 SHOP_PRICE_LEGS_UNSUPPORTED.

The currency must be one you have published (see Currencies). You can create a draft priced in a currency that is not published yet; publishing it, or editing a published listing onto it, is refused with 422 SHOP_CURRENCY_UNPUBLISHED. For an award listing, the award definition must also be published, or the publication is refused with 422 SHOP_AWARD_DEFINITION_UNPUBLISHED.

Every read reports each price leg three ways:

DiscountsCopy Anchor Link

A listing carries at most one discount, active over a time window:

{
  "discount": {
    "kind": "percentage",
    "percentage": "12.5",
    "startsAt": "2026-11-27T00:00:00Z",
    "endsAt": "2026-11-30T00:00:00Z"
  }
}

The window includes startsAt and excludes endsAt, so two back-to-back sales never overlap. The discount amount is rounded down, so a rounded price never gives away more than you authored: 1999 at 12.5% takes off 249 and costs 1750. Every read, event, cart and order computes the same effective price for the same instant. An invalid discount is refused with 422 SHOP_DISCOUNT_INVALID.

To schedule a sale on a live listing, PATCH the discount onto it ahead of time; the edit emits shop.listing.published with the new revision so your storefront can show the upcoming sale.

Per-player limitsCopy Anchor Link

{ "limit": { "maxPerPlayer": 3, "window": "week" } }

maxPerPlayer is an integer ≥ 1. window is day (the UTC day), week (the ISO week, in UTC) or total (for ever). A purchase that would exceed the limit is refused with SHOP_LIMIT_REACHED. A reversed or cancelled order gives its quantity back to the player's limit.

Edit a listingCopy Anchor Link

PATCH /v1/shop/listings/:listingKey accepts any of the fields above except listingKey. A field you omit keeps its value; an optional field you send as null is cleared.

An edit that sends stock for a counted listing that stays counted also carries stock.expectedRemaining, the count you last read, so a sale made while you edit is never undone. See Counted stock.

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 '{ "price": [{ "currencyKey": "coins", "amount": "450" }], "discount": null }'

Publish and retireCopy Anchor Link

curl -X POST "$REWARD_API_URL/v1/shop/listings/gold-frame/publish" \
  -H "Authorization: Bearer $TANITAR_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

Retiring takes an optional reason (at most 500 characters), shown in your own reads only:

curl -X POST "$REWARD_API_URL/v1/shop/listings/gold-frame/retire" \
  -H "Authorization: Bearer $TANITAR_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "End of season" }'

Read the catalogCopy Anchor Link

GET /v1/shop/listings returns every listing in any state, ordered by listingKey, up to 200. It takes no pagination parameters. Filter with the optional query parameters status (draft, published, retired), category and groupKey:

curl "$REWARD_API_URL/v1/shop/listings?status=published&category=cosmetics" \
  -H "Authorization: Bearer $TANITAR_API_KEY"

GET /v1/shop/listings/:listingKey returns one listing, or 404 SHOP_LISTING_UNAVAILABLE.

What your players seeCopy Anchor Link

Players read the catalog through GET /player/v1/shop/listings and GET /player/v1/shop/listings/:listingKey. They see published listings only, without status or the retirement reason. A draft or retired key reads as 404 SHOP_LISTING_UNAVAILABLE, while a published listing with nothing left is shown with availability: "sold-out". A catalog read never contains a code.

RefusalsCopy Anchor Link