Shop

The shop lets your players spend the currencies you run in Tanitar on items you publish. It lives in Reward Management, so every purchase debits the same ledger your grants credit, and every order is tenant-scoped: an order, a listing or a code never crosses from one organizer to another.

You manage the shop from your back-end with an API key (this guide), or from the dashboard (see Shop in the dashboard). Your players buy through the player plane, usually in your own Player client using a short-lived Player token.

The modelCopy Anchor Link

Every listing delivers through one of three fulfilment kinds:

How a purchase settlesCopy Anchor Link

sequenceDiagram
    participant P as Your Player client
    participant RM as Reward Management
    participant DB as Tenant database
    participant YOU as Your integration
    participant WH as Your webhook receiver
    P->>RM: Checkout with Idempotency-Key
    RM->>RM: Recompute the price on the server, check currency, listing and award
    RM->>DB: One transaction: debit, stock claim, per-player limit, award grants, order, outbox
    alt refused
        RM-->>P: Typed refusal (insufficient funds, sold out, limit reached, price changed)
    else settled
        RM-->>P: The order
        DB-->>WH: shop.order.settled
        opt code listing
            P->>RM: Re-read the codes of the order at any time
        end
        opt manual listing
            YOU->>RM: Claim, then record fulfilment
            DB-->>WH: shop.order.fulfilled
        end
        opt reversal
            YOU->>RM: Reverse with a reason
            DB-->>WH: shop.order.reversed
        end
    end

Three guarantees hold for every purchase:

• The server decides the price. The price a player pays is recomputed from the listing and its active discount at the moment of purchase. A player may send the total they expect; if it differs, the purchase is refused with SHOP_PRICE_CHANGED rather than silently repriced.
• All or nothing. The debit, the stock claim, the per-player limit, any award grant and the order commit in one transaction. A refused purchase leaves no debit and no stock claimed; its rejected order records why.
• Charged once. A retried purchase with the same Idempotency-Key returns the same order and never charges twice.

ScopesCopy Anchor Link

The shop has its own scopes, separate from rewards:*, so each responsibility can be given to a different key:

None of these implies another. In particular, shop:mutate can load codes but never read one back.

RoutesCopy Anchor Link

All shop routes are on Reward Management ($REWARD_API_URL).

EventsCopy Anchor Link

The shop publishes six events you can subscribe a webhook endpoint to:

Payloads are in the event catalog.