Audience: integrators (game stores, marketplaces, backends) and reviewers auditing how the Seller API stays cheap at high request volume.
Availability cache window with checkout holds#
GET /availability may be kept by your own HTTP cache for 60 s on deployments without checkout
holds and for 5 s where holds are enabled (whoami.capabilities.checkoutHoldEnabled),
because heldQuantity / sellableNow move every time a shopper starts checkout. Send
Cache-Control: no-cache for a commit-time read.
Example#
curl -s -X GET "https://api.avrix.io/api/seller/v1/catalog/snapshot" \
-H "Authorization: Bearer $AVRIX_API_KEY" \
-H "If-None-Match: "etag-from-prior-response""This document is the contract for read-side caching on the Seller API. It explains where caches live, when reads are free against your rate budget, and the anti-patterns that get your integration flagged as misbehaving.
For what to synchronise and in what order, see Catalog and allocations. This page covers only how to make those calls cheap.
TL;DR#
- The product reads (
/products,/products/{id},/products/{id}/pricing) and/catalog/snapshotcarry a weak ETag. Resending it asIf-None-Matchreturns304 Not Modifiedwith no body and no cost to yourreadbudget. The other catalog routes carry none yet; see ETags for the list. - Responses are
privateand key-scoped: no shared CDN cache stores them. Your own HTTP cache may keep a catalog body for themax-ageshown below and revalidate it withIf-None-Match. On the Avrix side a per-company response cache and a prebuilt catalog snapshot keep origin reads cheap. - Subscribe to webhooks (
product.updated,allocation.updated,order.fulfilled). Webhooks reduce tight polling; keep scheduled reconciliation / catalog delta polls (withIf-None-Match/updatedSince) as the safety net. - The rate limiter has a separate, 10× more generous bucket
(
read-cached) for cacheable catalog routes. If you keep getting 429s on/productsyou are doing something wrong; see Forbidden anti-patterns.
Where caches live#
Three tiers, each independently invalidated:
| Tier | Scope | Lifetime | Who pays for a miss |
|---|---|---|---|
| Your cache | your integration | max-age (60-300s); revalidate with If-None-Match | nobody if the ETag matches (304, no rate cost); otherwise the API |
| Per-company response cache | per seller company | 60-300s depending on route; dropped on grant, share and price writes | an origin round-trip |
| Origin database | global | source of truth | the database |
There is no shared CDN tier: every response is scoped to one API key, and a
shared cache keyed on a bearer token could serve one company another company's catalog.
The cheapest call is a revalidation that answers 304.
POST /orders/preview also reuses its read-only authority checks (SKU, allocation, sellability, agreement authority) for about 5 seconds per company, SKU and quantity, so a burst of previews on one SKU does not repeat them. Stock, price, territory, buyer geo and settlement are always computed live, and a refusal is never reused. A share revoke, agreement pause or grant change drops the reused checks at once; the preview is non-binding and POST /orders always checks everything again.
ETags#
These routes answer with an ETag header, e.g.
ETag: W/"a1b2c3d4..."
Send it back on the next request as If-None-Match:
GET /api/seller/v1/products HTTP/1.1
Authorization: Bearer …
If-None-Match: W/"a1b2c3d4..."
If the underlying data hasn't changed you get back 304 Not Modified:
- No body: nothing to download or parse.
- No cost to your
readbudget on the routes marked below; only the cheapread-cachedpre-flight counts. - It is not free for the server. On a body-hashed route Avrix still assembles
the response (from its per-company cache when it can, from the database
otherwise, plus the live sellability of each SKU) to compute the tag it
compares, so a
304saves you transfer and budget, not server time.
This makes per-minute polling against an unchanged catalog cheap in rate
budget and bandwidth. All polling clients should send If-None-Match on
the routes that carry a tag; a route without one answers 200 every time.
| Route | ETag | How it is computed | 304 debits read? |
|---|---|---|---|
| GET /products | Weak | Hash of the response body | No |
GET /products/{id} | Weak | Hash of the response body | No |
GET /products/{id}/pricing | Weak | Hash of the response body, on every contract date (new in 2026-11) | No |
| GET /catalog/snapshot | Weak | Derived from (maxUpdatedAt, totalProducts, changesCursor) | No |
GET /products/{id}/media/download | Strong ("media-...") | Hash of the asset list, without building the archive; also on HEAD | Yes: the media route is not on the cached read bucket |
GET /availability, /availability/{skuCode}, /allocations, /partners, /platforms, /regions, /catalog/changes, /catalog/checksum | None | Not tagged: poll them on the cadence the catalog guide gives | Not applicable |
The snapshot tag is stable across snapshot regenerations whose underlying
catalog hasn't changed, and moved by every change your change feed records,
price changes included (a price change never touches maxUpdatedAt on its own).
A body-hashed tag moves whenever any byte of the body would, including a
sellability change; the pricing tag also differs between contract dates where
the body does (see Pricing).
Rate-limit fairness#
The Seller API splits the rate bucket on kind:
read— read budget (sandbox cap, or a production key's fair-use limit; see Rate limits).read-cached— 10× thereadcap, used for the cacheable catalog routes' pre-flight check.write— order writes, key returns, webhook config writes.
For cacheable routes, the pre-flight only debits read-cached. The full
read budget is debited only when the route did fresh origin work:
| Response | Debits read? |
|---|---|
304 Not Modified (matched If-None-Match) | no |
200 with X-Cache: HIT (served from the shared response cache) | no |
200 with X-Cache: MISS or BYPASS (origin work) | yes |
Inspect the X-Cache, X-RateLimit-Limit, and X-RateLimit-Remaining
headers on every response to track what your integration is paying for.
Keeping sync cheap#
The canonical sync algorithm — snapshot, allocations, /catalog/changes
deltas, and the sellability gates — lives on
Catalog and allocations. Follow it there; the
three techniques below are what make it inexpensive.
1. Always send If-None-Match#
Persist the ETag from every response that carries one and resend it.
Unchanged data returns 304 with no body and no read cost, so a five-minute
poll of /products or a product's pricing against a static catalog costs
almost nothing. Routes without a tag are listed under ETags.
2. Let webhooks drive the delta#
| Event | Use case |
|---|---|
product.updated | Trigger a delta sync immediately instead of polling on a timer |
allocation.updated | Refresh availability for the affected SKU |
order.fulfilled / order.preorder_fulfilled | Update order status without polling GET /orders/{id} |
product.delisted | Remove the product from your storefront within seconds |
Webhooks plus deltas plus infrequent If-None-Match / reconciliation polls is a near-zero rate cost.
Do not drop scheduled reconciliation entirely — webhooks reduce tight polling; they do not replace it.
3. (High-volume browse) bundle with ?expand=#
For storefront browse pages that show 100 products with stock + price at once, use:
GET /api/seller/v1/products?expand=availability,pricing&limit=100
This adds per-row availability and pricing summaries to the list
response, replacing the canonical N+1 pattern of one list call followed by
100 detail calls. The availability field is advisory — call
/availability for commit-time accuracy.
Forbidden anti-patterns#
These will get your integration flagged in the Integration Health panel and may trigger account-level rate caps.
1. Polling /products every 30 seconds#
If you're polling /products more than once per minute without
If-None-Match, you are paying full rate cost for nothing. Use webhooks
plus GET /catalog/changes?cursor= instead (?updatedSince= on /products
misses price and stock changes: they never move a product's updatedAt).
2. Crawling the full catalog repeatedly#
Once you have your local catalog, never paginate from the start again. Use
/catalog/snapshot once at boot, then deltas. Repeated full crawls are the
surest way to exhaust your rate budget.
3. Calling /products/:id 100× after /products#
That's the N+1 anti-pattern. Use ?expand=availability,pricing on the list
endpoint. If you also need full pricing tables (regional SRP, edition-level
pricing), call /products/:id/pricing only on user navigation, never as
part of the initial browse render.
4. Calling /availability per row on a list page#
Use ?expand=availability on /products for the browse view. Reserve
/availability for the cart / commit step where accuracy matters.
5. Ignoring Retry-After#
When a 429 comes back, the Retry-After header tells you exactly when to
retry. Burst-retrying instead of waiting wastes your remaining budget and
extends the back-off.
6. Stripping or rewriting Idempotency-Key between retries#
Order writes (POST /orders, POST /keys/pull) are idempotent per
Idempotency-Key. Reuse the same key on retries — never generate a new
one. See Integration recipes.
7. Disabling gzip#
/catalog/snapshot is large by design. Always send Accept-Encoding: gzip.
Cache headers reference#
| Route | Cache-Control | Vary |
|---|---|---|
GET /products | private, max-age=90, stale-while-revalidate=300 | Authorization, Accept-Language |
GET /products/:id | private, max-age=90, stale-while-revalidate=300 | Authorization, Accept-Language |
GET /products/:id/pricing | private, max-age=300, stale-while-revalidate=300 | Authorization, Accept-Language |
GET /availability | private, max-age=60, stale-while-revalidate=300 | Authorization, Accept-Language |
GET /partners | private, max-age=120, stale-while-revalidate=300 | Authorization, Accept-Language |
GET /allocations | private, max-age=60, stale-while-revalidate=300 (plus a shared body cache per page, ~60s TTL) | Authorization, Accept-Language |
GET /catalog/changes | private, max-age=60, stale-while-revalidate=300 (per company) | Authorization, Accept-Language |
GET /catalog/checksum | private, max-age=60, stale-while-revalidate=300 (per company) | Authorization, Accept-Language |
GET /catalog/snapshot | private, max-age=300, stale-while-revalidate=600 | Authorization, Accept-Language, Accept-Encoding |
GET /orders (lookup, cart and list) | private, no-store on contract date 2026-12-01 and later; private, max-age=60 on older dates | Authorization, Accept-Language |
GET /orders/{orderId} | private, no-store | Authorization, Accept-Language |
GET /allocations guidance: treat it as inventory-sensitive checkout authority. Published
cache TTL is about 60 seconds; it uses the orders rate-limit class (not the catalog
read-cached pre-flight). Sync on a schedule / webhook and serve your storefront from the
mirror — do not call it per product page.
Order reads are not cached on contract date 2026-12-01 and later: a client polling an order
for ready, or after a refund, always reads the current state. On older dates a compliant
private cache may serve an order read up to 60 seconds old; pin 2026-12-01 or send
Cache-Control: no-cache on that poll.
GET /whoami is not cached by the API. It serves a light readiness summary
(~90s); pass ?diagnostics=1 only when you need full publisher and pricing
diagnostics.
To intentionally bypass all caches (debugging only), send:
Cache-Control: no-cache
See also#
- Catalog and allocations — the canonical sync algorithm these techniques make cheap
- Order preview — checkout pricing before order commit
- Webhooks — event types, signatures, delivery SLO
- Integration recipes — call order per flow
- Partner runbook — rate limits and support checklist