Listings and stock sync

A listing is one line of stock: a game, a lane, a realm (or a package on a top-up or gift-card lane), a price per some quantity, a minimum order, a stock count and a delivery time. Your software keeps a line per pool; the API keeps a listing per line. What ties them together is external_id: your own id for the line, unique per account, which every write can address instead of ours.

One listing at a time

• POST /v1/listings creates. Name the placement by slug (wow-classic, gold, whitemane-horde) or by id; a title is generated if you send none.
• PATCH /v1/listings/{id} changes price, stock, status or anything else. A listing never moves to another game, lane or realm; make a new line instead.
• PUT /v1/listings/by-external-id/{external_id} creates or updates by your id, which is the call most tools end up making.
• PUT /v1/listings/{id}/tiers replaces the volume ladder: up to three rungs, each starting above the one before it and cheaper than it. Checkout picks the rung an order reaches and freezes that price on the order.

A whole sheet

When your system is the truth, send the sheet. A stock sync lands up to a thousand lines a call and any number of calls, then applies as one decision in the background:

1. POST /v1/stock/syncs with { "mode": "replace" } or "merge". Replace means every listing with an external id the sheet does not mention goes to stock zero and pauses; merge leaves them alone.
2. PUT /v1/stock/syncs/{id}/lines with up to a thousand lines. Each line is checked on its own and its placement resolved; a bad realm name is reported in the answer to this call and counted as failed at commit, while the rest go on. The same external id staged twice keeps the later line.
3. POST /v1/stock/syncs/{id}/commit hands the sync to the worker and returns at once. GET /v1/stock/syncs/{id} shows committing becoming committed with counts, and /lines shows the result per line: created, updated, unchanged, paused or failed with a code.

POST /v1/listings/batch is the same engine in merge mode, opened, staged and committed in one call, for a sheet that fits in one request.

An unchanged line costs one read and no write, so sending the whole sheet every few minutes is fine. A 5,000-line sheet applies in well under a minute. Open syncs expire after an hour.

The sheet template

stock-sheet-template.csv has one row per line with the columns a sync line takes. Tiers are written as min_qty:price pairs separated by semicolons. Turn each row into a JSON line and send it; the samples do exactly that.

Names to ids

Your system says "Whitemane Horde" and ours says whitemane-horde. POST /v1/catalog/resolve takes the names you keep and ranks our games, lanes and realms against them, with a named faction deciding between the two sides of a realm. Use it once to build a crosswalk and store the slugs. GET /v1/catalog/changes?since= tells you what the catalog gained or renamed since a moment, so the crosswalk stays current without re-reading everything.

Gift cards and top-ups: the code vault

On a gift-card or top-up listing, stock the codes themselves with POST /v1/listings/{id}/codes. They are encrypted at rest and counted, never shown again; stock follows the vault. From then on every order on that listing is accepted and delivered the moment it is paid, with the codes attached for the buyer. A vault short of an order's quantity leaves that order for you to deliver by hand, as before.

Low stock

Set low_stock_alert_qty on a listing and you receive listing.low_stock when a sale crosses it and listing.sold_out at zero. Either is a reason to top the line up, and both are the cheap way to know without polling.