Read this before you write catalog sync. The Avrix catalog model separates what you can see from what you can sell, and integrations that ignore the distinction ship storefronts that list products they cannot deliver.
Example: your allocations#
The first call of every sync: GET /allocations lists your capacity grants and says which SKUs
you can sell.
curl -s -X GET "https://api.avrix.io/api/seller/v1/allocations" \
-H "Authorization: Bearer $AVRIX_API_KEY"Example: the catalog snapshot#
The second: GET /catalog/snapshot returns everything shared with you in one response, to merge
with the allocations on the SKU id.
curl -s -X GET "https://api.avrix.io/api/seller/v1/catalog/snapshot" \
-H "Authorization: Bearer $AVRIX_API_KEY"Who needs this#
Engineers building catalog sync, merchandising feeds, or checkout gates that must know which SKUs are actually purchasable.
TL;DR#
- Catalog feeds answer visibility;
GET /allocationsanswers capacity and sellability. - Merge both on the SKU id. A SKU is sellable only when
GET /allocationssayssellable: true; that needs a share as well as an allocation, so an allocation without a share is not sellable. - Four gates must open before checkout: BMA → share → allocation → territory pricing.
- Echo preview’s
unitPriceCentsasexpectedUnitPriceCentson commit.
The core idea#
Two different questions have two different answers, from two different endpoints:
| Question | Endpoint | Answer |
|---|---|---|
| What products am I permitted to see? | GET /products, GET /catalog/snapshot | The shared catalog |
| What can I actually sell right now? | GET /allocations | Your capacity grants |
Neither is the sellable set on its own. Your sellable catalog is the SKUs that are in both
and carry sellable: true on GET /allocations. Each side contains entries the other does
not, and none of those is sellable.
The four gates#
In plain English: the vendor must (1) agree to trade with you, (2) share the specific SKU, (3) grant you units to sell, and (4) price the buyer’s country under the API model. Miss any one and checkout fails, even if the product looks great on a browse page.
A SKU becomes sellable through your storefront only when all four gates are open.
Gate 1: Business Model Agreement. A BMA between you and the vendor establishes the commercial
terms for Seller API trading under the API business model: settlement basis and the scope of
what may be traded. Without an active BMA nothing that vendor owns is available to you at all.
Check hasActiveBma on GET /whoami. A missing or lapsed BMA produces CONTRACT_NOT_ACTIVE.
Gate 2: SKU share. Within a BMA, the Content Owner shares specific SKUs under each title you accepted. A shared SKU appears in your catalog feeds. A title the Content Owner publishes later reaches you only as an offer you accept in the console; pending offers are listed by GET /api/seller/v1/partners/{connectionId}/offers. Sharing is about visibility and metadata rights, not stock.
Gate 3: Allocation. An allocation grant gives you actual capacity: a number of units you may draw against. Without an allocation you cannot fulfil, regardless of visibility.
Gate 4: Territory pricing. Under the API business model, a SKU is transactable in a given country only if a catalog list price exists for that country. Without one, orders fail with CATALOG_PRICE_NOT_SET even when the first three gates are open.
Why one endpoint is never enough#
The two feeds are gated differently, so each lists SKUs the other does not.
| SKU situation | In /products and /catalog/snapshot? | In /allocations? | Sellable? |
|---|---|---|---|
| Shared and allocated | Yes | Yes | Yes |
| Shared, not allocated | Yes | No | No |
| Allocated, not shared | No | Yes | No (NO_SKU_SHARE) |
| Neither | No | No | No |
Read the third row carefully. An allocation without a share is not sellable.
GET /allocations lists the grant with sellable: false and the blocker NO_SKU_SHARE, the
catalog feeds do not list the SKU, and an order for it is refused. Sellability needs gate 2 (the
share) as well as gate 3 (the allocation), so there is no separate "allocation-only" path to
build.
The second row is the opposite failure and the more common one: SKUs you can see, describe, and list, but cannot deliver. Listing them produces checkout failures after the buyer has committed.
The three product surfaces#
Product data is deliberately split across three surfaces rather than returned as one payload. Each serves a different access pattern, and using the wrong one is a performance problem rather than a correctness one.
| Surface | Endpoints | Use for |
|---|---|---|
| Browse and sync | GET /products, GET /catalog/snapshot, GET /catalog/changes, POST /catalog/exports | Building and maintaining your local catalog mirror |
| Rich metadata | GET /products/{id}, GET /products/{id}/pricing | Product detail pages: artwork, descriptions, ratings, regional prices |
| Checkout authority | GET /allocations, GET /availability, POST /orders/preview | Deciding whether and at what price to sell |
Do not call the checkout-authority endpoints to render a listing page, and do not rely on browse-and-sync data to decide whether to charge a buyer.
GET /products narrows and orders the list on every contract date: platform (codes from
GET /platforms), externalReference (with externalReferenceSource), releaseDateFrom and
releaseDateTo, launchPhase, tradingState, productType, and sort (-createdAt, the
default and the order the list always had, createdAt, -updatedAt, updatedAt, name,
-name). meta.total counts the filtered list, and a cursor belongs to the sort it was issued
with: sending it with another sort answers 422. To map ids you already hold (a Steam app or
package id, a platform product id) to Avrix products, GET /products/lookup?externalReference=
takes up to 100 comma-separated values and answers one row per value, in the order sent, with the
SKU and the reference that matched; a value nothing shared with you carries is answered with no
matches rather than an error.
Some filters have two spellings. partner is the vendor filter on GET /products and
GET /catalog/checksum; publisherCompanyId is its deprecated spelling. countryCode is the
country filter on GET /products/{id}/pricing and GET /availability; country is its
deprecated spelling. Both spellings keep working, a request that uses only the old one gets an
X-Avrix-Deprecated-Parameter header naming the new one, and a request that sends both with
different values is refused with 422, so neither silently wins.
Product detail is large by default. GET /products/{id}?omit= leaves out the blocks you do not
render (assets, eula, localizedDescriptions, systemRequirements, relatedProducts, or
releasePricing for the deprecated release-level prices), and
locales= keeps only the languages you sell in. Media arrives two ways: the assets block on
product detail lists the files as direct URLs, and GET /products/{id}/media/download packs them
into one ZIP. Copy the files into your own storage rather than linking to them: a URL stops
resolving when the Content Owner replaces or removes the file. See
Media for the archive's contents and headers.
The catalog sync algorithm#
This is the one recommended algorithm. Implement it as written.
Step 1: Cold start#
Pull the full shared catalog once.
curl -s "https://api.avrix.io/api/seller/v1/catalog/snapshot?pricing=territory" \
-H "Authorization: Bearer avrix_sk_your_key_here"
For a large catalog, enqueue an immutable gzip NDJSON artifact instead of holding the
snapshot request open: POST /catalog/exports returns 202 { exportId, status: "pending" }.
Poll GET /catalog/exports/{exportId} (or wait for catalog.export_ready) for a short-lived
signed URL, checksum, and expiry. The live snapshot endpoint stays available.
A build that fails is retried with backoff; attempts counts the tries. If it still fails, the
export shows status: "failed" with error: { code: "EXPORT_FAILED", message, retryable: true }.
Sending the same POST /catalog/exports again requeues that export (the response reports its real
status, pending), so there is no need to change your filters to get a fresh one.
{
"meta": {
"totalProducts": 218,
"maxUpdatedAt": "2026-08-04T21:14:07.482Z",
"changesCursor": "eyJ2IjoxLCJzZXEiOjQxMDB9",
"availabilityCursor": "eyJ2IjoxLCJzZXEiOjkxMn0",
"pricing": "territory",
"generatedAt": "2026-08-04T21:15:02.000Z",
"version": 1
},
"data": [
{
"id": "3f9a...",
"readableId": "prd_3f9a...",
"name": "Example Game",
"slug": "example-game",
"sharedSkus": [
{
"id": "8b9d...",
"skuCode": "EXAMPLE-WIN-US",
"platformCode": "windows",
"editionName": "Standard",
"srpPriceCents": 5999,
"srpCurrencyCode": "USD",
"sellable": true,
"readinessBlockers": [],
"territoryPrices": [
{ "countryCode": "US", "basePriceCents": 5999, "currencyCode": "USD", "currencyExponent": 2, "zone": null, "sellable": true, "blockedReason": null },
{ "countryCode": "JP", "basePriceCents": 6800, "currencyCode": "JPY", "currencyExponent": 0, "zone": null, "sellable": true, "blockedReason": null }
]
}
]
}
]
}
Persist meta.changesCursor. It is your delta cursor: the position of your change feed when the
snapshot was assembled, and the value you pass to GET /catalog/changes?cursor= in step 4.
meta.maxUpdatedAt is the latest product updatedAt in the snapshot and only serves
GET /products?updatedSince= for metadata and lifecycle deltas. A price change never moves a
product's updatedAt, so it is not a pricing watermark. The snapshot returns your entire
visible catalog in one gzip-optimized response. There is no paging; meta.nextCursor is null.
Very large stores (tens of thousands of SKUs) can add ?format=ndjson to receive the same
snapshot as newline-delimited JSON: the first line is the meta object, then one product per
line, streamed so your importer can parse line-by-line in constant memory instead of loading one
giant document. ETag semantics are identical: send If-None-Match and you get 304 Not Modified when nothing changed, whichever format you use.
Step 2: Fetch allocations#
curl -s "https://api.avrix.io/api/seller/v1/allocations?limit=100" \
-H "Authorization: Bearer avrix_sk_your_key_here"
{
"data": [
{
"id": "f8b1...",
"readableId": "alc_f8b1...",
"skuId": "8b9d...",
"skuCode": "EXAMPLE-WIN-US",
"sellable": true,
"remaining": 942,
"pricePerKeyCents": 4199,
"currencyCode": "USD",
"readinessBlockers": []
},
{
"id": "c410...",
"readableId": "alc_c410...",
"skuId": "77e2...",
"skuCode": "EXAMPLE-MAC-US",
"sellable": false,
"remaining": 500,
"pricePerKeyCents": 3999,
"currencyCode": "USD",
"readinessBlockers": ["NO_SKU_SHARE"]
}
],
"meta": { "limit": 100, "count": 2, "nextCursor": null, "hasMore": false, "nextUrl": null }
}
limit is at most 100 (default 50); a larger value answers 422. Follow meta.nextCursor
while meta.hasMore is true, as on every list (Lists and pagination). With
sellableOnly=true a page can be short or empty while hasMore is true on dates before contract
date 2026-12-01; keep following the cursor. Each row's id is the allocation id: the value webhooks call allocationId,
GET /allocations/{id} and PATCH /allocations/{id} take in the path, and POST /allocations/requests
takes as allocationId (grantId is its older name, still accepted). GET /allocations/{id} reads
one allocation whatever its status, so a paused or revoked allocation a webhook names stays readable.
EXAMPLE-MAC-US did not appear in the snapshot. It is allocated but not shared, so it is not
sellable until the vendor shares it.
The rows above are wholesale grants. pricePerKeyCents is an advisory summary of what that
grant costs you; null means there is no wholesale price, which is always the case under the
API business model, where the sale is booked at the territory list price and the Content Owner
is paid a share of it (see Pricing below). It is never 0: an unpriced grant reads as
null on pricePerKeyCents, currencyCode and currencyExponent alike.
readinessBlockers explains why anything with sellable: false is blocked.
After the first full fetch, poll allocations as deltas instead of refetching everything: each row
carries updatedAt, and GET /allocations?updatedSince=<your max updatedAt> returns only grants
mutated since then (resizes, revocations, status changes). Overlap the timestamp by a few seconds
between polls so nothing is missed. Allocations reads sit in the catalog rate class, so delta
polling never competes with your checkout budget. Sellability shown in catalog responses
(sharedSkus[].sellable) is computed from these same grant rows and grant changes invalidate the
cached catalog surfaces, so allocations and catalog readiness cannot drift apart for longer than one
poll cycle.
Step 3: Merge#
Build the sellable set from the allocation rows and join it to the catalog on the SKU id: skuId
on an allocation row is id on a sharedSkus[] entry.
- Allocation row with
sellable: true: sellable. Take its metadata from the catalog entry with the same SKU id. - Allocation row with
sellable: false: not sellable.readinessBlockerssays why (NO_SKU_SHAREwhen the SKU is allocated but not shared). - Catalog only (no allocation row): not sellable. Keep it for reference if you want, but never expose a buy button.
Store sellable from the allocation, not from the catalog decoration.
Step 4: Incremental updates#
Poll for deltas from the stored cursor: the snapshot's meta.changesCursor on the first run,
then the meta.nextCursor of the last page you applied. Every change to your view of the catalog
is recorded here, price changes included: a repriced SKU arrives as updated with
changedFields: ["pricing"] (it never moves the product's updatedAt).
curl -s "https://api.avrix.io/api/seller/v1/catalog/changes?cursor=eyJ2IjoxLCJzZXEiOjQxMDB9" \
-H "Authorization: Bearer avrix_sk_your_key_here"
{
"data": {
"changes": [
{ "productId": "9c22...", "type": "added", "occurredAt": "2026-08-05T07:01:11.204Z", "changedFields": ["availability", "metadata"] },
{ "productId": "3f9a...", "skuId": "8b9d...", "skuCode": "EXAMPLE-WIN-US", "type": "updated", "occurredAt": "2026-08-05T07:44:02.119Z", "changedFields": ["pricing"] },
{ "productId": "1a04...", "type": "removed", "occurredAt": "2026-08-05T08:02:19.771Z", "changedFields": ["availability"] }
]
},
"meta": { "nextCursor": "eyJ2IjoxLCJzZXEiOjQyMTd9", "hasMore": false }
}
Apply the latest change per product
The feed is a log, not a state. A product can carry several entries in one window: removed
followed by added when the content owner pauses and resumes an agreement, or removed + added
pairs when shares are re-scoped. Reduce the page to the newest entry per productId (by
occurredAt) before acting, and never delist a product that your latest GET /products or
snapshot still returns: a stale tombstone must not override a listing you have just received.
Cursor pagination (preferred)
Persist meta.nextCursor and pass it back as ?cursor=. It is an opaque, monotonic feed
position that is safe against timestamp ties and clock skew. nextCursor is the position of the
last change in the page, so it is your resume point whether the page was full or not; it is
null only when the page was empty, so keep the cursor you sent. meta.hasMore is true when the
page was cut at limit: poll again right away instead of waiting for the next tick. The
snapshot's meta.changesCursor and the checksum's changesCursor are positions on the same
feed. When both cursor and since are sent, the cursor wins. The feed also carries meta.limit
and meta.nextUrl, like every list (Lists and pagination).
since boundary (compatibility)
since remains supported and is exclusive: the server returns events with occurredAt
strictly after the timestamp you pass (occurred_at > since). After you apply a page,
advance to the last occurredAt, or better, switch to meta.nextCursor.
changedFields
Each entry lists the changed facets (pricing, availability, metadata, territory, or
relationships), so one changed price no longer forces a whole-product refetch: on pricing,
refetch GET /products/{id}/pricing only. An empty array means the facet is unknown (events
recorded before facet tracking): refetch the product.
Availability changes
Stock and sellability have their own feed, GET /availability/changes. Start it from the snapshot's meta.availabilityCursor and page it like the catalog feed (cursor, meta.nextCursor, meta.hasMore). stock_down and stock_up carry an allocation's new remaining count; unsellable and sellable switch a SKU's Buy button and list the readiness reasons. Each state is recorded once, so the feed stays short.
curl -s "https://api.avrix.io/api/seller/v1/availability/changes?cursor=eyJ2IjoxLCJmZWVkIjoiYXZhaWxhYmlsaXR5Iiwic2VxIjo5MDB9" \
-H "Authorization: Bearer avrix_sk_your_key_here"
{
"data": {
"changes": [
{ "skuId": "8b9d...", "skuCode": "EXAMPLE-WIN-US", "allocationId": "c41e...", "type": "stock_down", "remaining": 41, "reasons": [], "occurredAt": "2026-09-25T09:12:40.118Z" },
{ "skuId": "8b9d...", "skuCode": "EXAMPLE-WIN-US", "allocationId": null, "type": "unsellable", "remaining": null, "reasons": ["NO_TERRITORY_PRICING"], "occurredAt": "2026-09-25T09:30:02.551Z" }
]
},
"meta": { "nextCursor": "eyJ2IjoxLCJmZWVkIjoiYXZhaWxhYmlsaXR5Iiwic2VxIjo5MDJ9", "hasMore": false }
}
Request the snapshot with ?pricing=territory and every shared SKU carries territoryPrices, its list price in each country with the country's price zone ({ code, label } or null): a cold start then needs no GET /products/{id}/pricing call per product. Every price also says whether you can sell at it: sellable is false, with blockedReason CURRENCY_NOT_PRICED_FOR_COUNTRY, when the price is kept in a currency the content owner does not allow for that country (a platform's own price, such as a Steam price in PLN for an owner that sells Poland in EUR). You may show it as the country's price, but an order there is refused until the owner sets a price in an allowed currency or allows this one. GET /products/{id}/pricing carries the same two fields; on contract date 2026-12-01 and later its answer also covers your footprint, your agreement and the SKU's territory (see Pricing). A price can also be a fallback: fallbackFromCurrency names the store's currency for the country (say PLN) when the owner excludes it and prices the country in another allowed currency; the price is then the platform's highest price in currencyCode, and it sells as any other price (sellable: true). It is null on every other price. A catalog change about one SKU (a price, a SKU pause, a SKU shared or unshared) names it with skuId and skuCode, so you refetch that SKU only. A 404 on that refetch, or a product that no longer lists the SKU, means it is no longer shared with you: remove it from your listing.
Tombstones (type: "removed") and retention
removed rows are tombstones: delist the product from your storefront immediately. Delta events
are retained for at least 30 days: a store offline for up to a month catches up via deltas
alone. If your cursor is older than retained history, or GET /catalog/checksum drifts from your
mirror, cold-start with GET /catalog/snapshot and rebuild. Do not invent local replay from
stale state. On contract date 2026-12-01 and later both feeds tell you: a cursor or since
older than retained history answers 409 CATALOG_RESYNC_REQUIRED with details.reason
retention_expired. Earlier dates serve the rows still kept after that position without a
signal, so compare your last poll time with the retention yourself.
What the platform emits when a product leaves (or partially leaves) your view:
- Archive / full delist: the product stops being live:
removed. It also disappears fromGET /productsandGET /catalog/snapshot. - Unshare:
removedwhen the unshare ends your access to the product (it drops from list/snapshot), unless another agreement still shares the product with you. When the Content Owner stops sharing some SKUs of a product but others stay shared, or shares new SKUs under a product you already see, each of those SKUs arrives asupdatedwithchangedFields: ["availability"]and itsskuIdandskuCode, the same entry a SKU-level delist writes. RefetchGET /products/{productId}(an unshared SKU is no longer listed, so remove it from your listing; a newly shared one is) and re-readGET /allocationssellablefor those SKUs. - Release- or SKU-level delist while the product stays live:
updatedwithchangedFields: ["availability"]: refetch the product and re-readGET /allocationssellablefor the affected SKUs.
Advance your cursor only after the batch has been applied successfully. If application fails partway, keep the old cursor and retry: replaying a page is safe because both paging modes are exclusive of already-applied positions.
Re-run step 2 on every sync. Allocations change independently of catalog metadata: capacity is consumed, grants are extended, and sellability flips without any catalog event.
Step 5: Drift detection#
curl -s "https://api.avrix.io/api/seller/v1/catalog/checksum" \
-H "Authorization: Bearer avrix_sk_your_key_here"
The digest covers the set of visible product IDs for your seller (optionally filtered by
partner) together with each product’s updated_at, hashed as
sha256-sorted-product-rows-v1 (digest, totalProducts, maxUpdatedAt). Treat a checksum
change as a signal to cold-start. Do not try to recompute the digest locally against a
partial mirror.
The response also carries changesCursor, your current change-feed position. It advances on
every recorded change, price changes and SKU share changes included. The digest never sees
those, because neither touches a product row: it is product-level by design, so a SKU shared or
unshared under a product you still see leaves it unchanged and moves changesCursor. When the
cursor differs from the one you last applied, there are deltas waiting in step 4; when digest
differs from your mirror, cold-start. The cursor is seller-wide even when partner scopes the
digest.
Compare on a schedule (daily is typical). Drift usually means a dropped delta batch or a cursor that fell outside retained history. Recover with a full cold start (step 1).
Step 6: Event-driven refresh#
Subscribe to these events to refresh sooner than your poll interval:
| Event | Refresh |
|---|---|
product.updated | The affected product |
product.announced | Catalog delta |
product.delisted | Delist immediately |
release.available | Catalog delta |
release.date_changed | Listing dates; notify pre-order buyers |
sku.pricing_updated | Territory pricing for that SKU |
sku.sellability_changed | Buy button for that SKU (confirm with GET /allocations) |
allocation.updated | Allocations |
allocation.depleted | Allocations: stop selling that SKU |
allocation.low_stock | Allocations: consider throttling (repeated while low) |
allocation.running_low | Allocations: reorder or ask for more keys (once per crossing of your threshold) |
allocation.request_decided, allocation.request_cancelled | Your allocation request was decided, or withdrawn |
Webhooks supplement polling; they do not replace it. Delivery is at-least-once, not exactly-once, and an endpoint outage means missed events. Keep the scheduled poll running.
Allocation revocation semantics#
allocation.updated payloads carry a reason:
created, resized (ceiling change), rebalanced, approved, pulled, returned,
updated, paused, revoked, depleted, replenished (an automatic top-up grew the ceiling),
or hot_drop_mode_changed. Treat an unknown reason as updated.
When a publisher revokes or pauses a grant mid-flight:
- Open checkout holds and hot-drop reservations for that grant are cancelled: an in-flight
POST /orders/commitfor a cancelled reservation returnsRESERVATION_GONE, and aPOST /orderswith a cancelledcheckoutHoldIdfails hold validation. allocation.updatedis delivered withreason: "revoked"(or"paused"); stop selling the SKU immediately and treatGET /allocationsas authoritative on the next sync.- Already-fulfilled orders are unaffected: revocation is never retroactive.
Automatic top-ups#
Set a top-up threshold on an allocation with PATCH /allocations/{id} (replenishThreshold, and optionally replenishQuantity). Both allocation writes, this one and POST /allocations/requests, need seller:allocations:write; keys that hold seller:orders:write or the legacy seller:keys:pull keep working. When a pull leaves remaining at or below it, Avrix tops the allocation up within the Content Owner's rules and sends allocation.replenished; outside the rules it files an allocation request for the Content Owner to review, exactly as POST /allocations/requests would. GET /allocations/{id}/replenishments shows the rules and every top-up, and the Content Owner sees the same history. The PATCH answer returns those rules and effective: what a crossing will actually do under them (automatic, request or off, with the quantity and what limited it), so a threshold the rules will not honour shows when you set it. On contract date 2026-12-01 and later a revoked allocation is refused with 409 CONFLICT (details.reason: allocation_revoked). The same threshold drives allocation.running_low, sent once each time remaining falls to it (10% of quantityLimit when you set none). It does not drive allocation.low_stock: that event uses a fixed 10% of quantityLimit and is sent with every allocation update while remaining is at or below it (see the event reference and Stock and reservations).
Rehearse it in sandbox. An allocation request waits for a person at the Content Owner, so the
sandbox vendor can decide it for you: POST /sandbox/allocations/requests/{requestId}/resolve
with {"decision": "approved"} (optionally grantDelta) or {"decision": "denied"} sends
allocation.request_decided to your sandbox endpoints, and allocation.updated on approval.
Approvals follow the production stock rule, so rehearse them on SANDBOX-ALLOC-REQUEST-001, an
allocation of 5 over 30 keys in stock; an approval needs your store's isolated sandbox
environment, while a decline also works on the shared sandbox. To test your stock handlers without
selling anything, POST /sandbox/allocations/{allocationId}/stock-events with
{"event": "low_stock"} or {"event": "depleted"} sends allocation.low_stock or
allocation.depleted for that allocation. See
Sandbox.
Launch-window reservations#
For a big release the Content Owner can reserve keys for your store during a launch window. The
allocation then carries launchWindow on GET /allocations: startsAt, endsAt,
reservedQuantity, state (scheduled, open or closed) and setAside.
- While
open,setAsidekeys are held for your store. No other store can take them, and your orders (POST /orders,POST /orders/commit,POST /keys/pull) use them before the shared pool. Your allocation'sremainingstill caps what you can take; the window guarantees the stock, not extra quota. setAsidecan be lower thanreservedQuantitywhen the shared pool or your allocation could not cover the full quantity at the moment the window opened. The Content Owner is told.- When it closes, the keys you did not use go back to the shared pool. A closed window stays on the allocation for a day.
- Request-rate limits are platform-wide and do not change with a launch window. See Rate limits for per-key overrides during a launch.
Cadence#
| Operation | Suggested frequency | Notes |
|---|---|---|
GET /catalog/snapshot | Cold start and after checksum drift only | Catalog rate class |
POST /catalog/exports | Large-catalog bootstrap when you want a resumable artifact | 202 { exportId }; poll GET /catalog/exports/{exportId} |
GET /catalog/changes | Every 5–15 minutes, plus on webhook | Opaque cursor (or exclusive since); repeat while hasMore |
GET /allocations | Every 5–15 minutes, plus on allocation webhooks | Catalog rate class; published cache guidance ~60s |
GET /catalog/checksum | Daily | Integrity signal: cold-start on change |
GET /availability | At checkout, not during browsing | |
POST /orders/preview | When the buyer reaches checkout |
Honour ETag and Cache-Control on catalog reads; a conditional request that returns 304 does
not count against your rate budget. See the caching guide.
Money fields#
Every money field in the Seller API is an integer in the minor units of the currency named
next to it (currencyCode, or the *CurrencyCode field with the same prefix). There are no
decimals in JSON, and the number of minor-unit digits is not always two: next to each money
field a currencyExponent (or <prefix>CurrencyExponent) says how many there are, so
amount = cents / 10^currencyExponent.
| Currency | currencyExponent | Wire value | Amount |
|---|---|---|---|
| USD | 2 | 1999 | 19.99 USD |
| JPY | 0 | 2350 | 2350 JPY |
| KWD | 3 | 6500 | 6.500 KWD |
Never divide by 100 unconditionally: a JPY price divided by 100 lists a 2,350 yen game at 23 yen.
Read the exponent from the same object as the amount. The two prices on sku.pricing_updated
(previousPricing, newPricing) can be in different currencies and each carries its own; a band
with two currency pairs (expand=pricing) carries one exponent per pair. When an amount is
null, its exponent is null too.
One name per amount. An amount's name ends in Minor. A name ending in Cents, and the bare
cents of a per-currency bucket, is an older name of the same value: every success response and
every webhook event that carries one also carries its Minor name (basePriceCents and
basePriceMinor, unitPriceCents and unitPriceMinor, cents and amountMinor). Read the
Minor name; the Cents names stay on the wire. Request fields keep their names, so you still send
expectedUnitPriceCents. The table lists the older names, which the API reference documents next to
their Minor names. See Naming conventions.
| Field | Meaning | Where it appears |
|---|---|---|
basePriceCents | The list price of one SKU in one country: what a sale under the api business model charges | GET /products/{id}/pricing skus[].prices[] and the deprecated release-level prices[], GET /catalog/snapshot?pricing=territory sharedSkus[].territoryPrices[], GET /products/{id} skus[].prices[] |
priceCents | The same list price for one requested country, or the old and new price of a price change | GET /availability?countryCode= price, sku.pricing_updated (top level, previousPricing, newPricing) |
srpPriceCents | Suggested retail price in your pricing country (srpCurrencyCode, with srpCurrencyExponent); a browse hint, never a sale price | GET /products and GET /catalog/snapshot sharedSkus[] |
pricePerKeyCents | Wholesale contract price per key under wholesale / pre_order; null means no wholesale price, never 0, and it is always null under businessModel: api | GET /allocations, catalog sharedSkus[] (with currencyCode and currencyExponent) |
listPriceFromCents | Lowest list price among the shared offers of a product, in your pricing country; a browse hint | GET /products rows (with listPriceCurrencyCode), expand=pricing echo (with listPriceCurrencyExponent) |
wholesaleFromCents | Lowest priced wholesale / pre_order grant on a product; advisory | GET /products?expand=pricing (with wholesaleCurrencyCode and wholesaleCurrencyExponent) |
unitPriceCents | The binding unit price of a quote or hold; echo it as expectedUnitPriceCents on commit | POST /orders/preview lines[], POST /orders/hold, GET /activity economics |
*Minor (grossMinor, netMinor, vatMinor, salesPriceGrossMinor, ...) | Settlement and declared-retail amounts | integrationOrderContext (your own declaration, in its currencyCode; the echo on finance rows and order webhooks adds currencyExponent), preview settlement (in currency, with currencyExponent), GET /finance/api-sales declaredRetail (in retailCurrencyCode, with currencyExponent), finance statements and settlements (in the row's currencyCode, with currencyExponent) |
*Cents on finance and order reads | Sale, share, fee, balance and invoice amounts | GET /finance/api-sales, GET /finance/statements, GET /finance/ledger, GET /finance/invoices, GET /finance/summary, GET /orders list rows, invoice.created, invoice.issued, invoice.paid and payout.file_ready: each object carries currencyExponent beside its currencyCode. The GET /finance/summary report total totalNetRevenue is in major units (a decimal); read totalNetRevenueMinor instead. The payout reconciliation file carries paymentCurrencyExponent for totalCents and movement amountCents, and currencyExponent on each sale |
Most of these name one of three prices. Read them like this:
- To show a price on a listing page, read
listPriceFromCents(the lowest price on the product) orsrpPriceCents(one SKU). Both are in your pricing country: the country of your company's default currency, or the United States when none is set. They are browse hints, not what a sale in another country charges. - To show the price in the buyer's country, read
basePriceCentsfor that country (GET /products/{id}/pricing, orterritoryPriceson a snapshot taken with?pricing=territory), orpriceonGET /availability?countryCode=. - To charge, read
unitPriceCentsfromPOST /orders/previewand echo it on commit. It is the only one of the three that binds.
Pricing#
Seller API partnerships use the API business model. A sale is booked at the territory
catalog list price for the buyer's country, less any approved promotion (or at the price snapshot
bound by an active checkout hold). That is the price unitPriceCents quotes and
expectedUnitPriceCents binds.
It is not what you owe. Under the API model the Content Owner is paid its share of that price,
net of the consumer VAT you declare you charged, and the rest is yours: the
settlement basis works the
numbers through. The catalog does not carry a cost or a share, on purpose: the share is a term of
your agreement, fixed on each sale when it commits, and the VAT deducted depends on the buyer's
country and on what you declare at checkout, so a cost printed on a catalog row would be a guess
that the sale could contradict. The preview's settlement block shows the VAT basis without the
shares for the same reason. Each committed sale states its split: revenueSharePercent,
publisherShareCents and sellerShareCents in the order's economics, and the settlement
block of each line on GET /finance/api-sales. pricePerKeyCents is a wholesale price and is
always null under the API model.
GET /products/{id}/pricing lists every country's price with sellable and blockedReason. On
contract date 2026-12-01 and later they are the order path's answer for that country: your
footprint, the currencies and territory your agreement grants, the SKU's territory and region
locks, the catalog price and the priced currency, in the order an order checks them, the same
answer GET /availability?countryCode= gives. A country you have not declared you sell in reads
sellable: false with FOOTPRINT_COUNTRY_NOT_DECLARED. Earlier dates answer only whether the
price's currency is allowed for the country (CURRENCY_NOT_PRICED_FOR_COUNTRY), so a price
there can read sellable: true and still be refused at checkout. Whether you hold an allocation
for the SKU is not part of this answer: that is GET /allocations.
Safe rule: echo the unitPriceCents returned by the most recent POST /orders/preview for the
same SKU, quantity, and country as expectedUnitPriceCents (the field alias
expectedWholesaleUnitPriceCents is accepted and must match if both are sent).
Price guards fail closed. Omitting expectedUnitPriceCents is rejected with
EXPECTED_UNIT_PRICE_REQUIRED. There is no default. A stale value is rejected with
CATALOG_PRICE_MISMATCH rather than being silently repriced. (A legacy
WHOLESALE_PRICE_MISMATCH code may still appear in the contract for non-API grants; it is not
used by current Seller API partnerships.) This is deliberate: you can never be charged a price you
did not see.
Your retail price is entirely yours. Nothing above constrains what you charge the buyer.
Why a SKU is not sellable#
Symptom → missing gate#
| What you see | Likely missing gate | What to check |
|---|---|---|
| Empty partners / no catalog at all | 1: BMA | GET /whoami → hasActiveBma; ask your vendor / Avrix contact |
| SKU absent from snapshot and allocations | 2: Share (or no BMA) | Vendor share scope; partners list |
SKU in catalog, sellable: false, blocker NO_ALLOCATION | 3: Allocation | Capacity grant inactive or never issued |
SKU allocated, preview/order fails with CATALOG_PRICE_NOT_SET / territory errors | 4: Territory pricing | Buyer countryCode / salesCountryCode vs catalog price |
Catalog shows “coming soon”, commit returns PRODUCT_NOT_SELLABLE | Lifecycle (not a commercial gate) | launchPhase must be available, or pre_order on the pre-order path; see Launch phases |
readinessBlockers codes#
readinessBlockers on GET /allocations names the gate that is closed.
| Blocker | Gate | Resolution |
|---|---|---|
NO_SKU_SHARE | 2 | The vendor has not shared this SKU with commit authority |
NO_ALLOCATION | 3 | Shared but no capacity granted / grant inactive |
NO_TERRITORY_PRICING | 4 | No territory price for the country (API model) |
PRODUCT_NOT_SELLABLE | Lifecycle | Not transactable: not yet released (outside the pre-order path), discontinued or archived |
PRODUCT_EXCLUDED | 2 | Product excluded from your share. No longer emitted: scope is the explicit share list. |
PAYMENT_NOT_CLEARED | 3 | The grant's payment has not cleared: wholesale and pre-order grants need confirmed payment. Commits answer 402 until it clears; recommendedAction is complete_allocation_payment |
Gates 1 through 3 are commercial and resolve through your vendor relationship, not through the API.
Launch phases#
Separate from the four gates, each product carries its lifecycle in three fields, and each answers a different question. Catalog feeds use a broader visibility rule; orders use a stricter sellability rule.
| Field | Values | Question it answers |
|---|---|---|
launchPhase | announced, pre_order, available (draft is never shown to you) | How far the release has come |
tradingState | open, paused, discontinued | Whether the Content Owner is trading it now |
isArchived | true, false | Whether it has been withdrawn from the catalog |
How they combine:
| State | Listed in catalog feeds | Orderable |
|---|---|---|
launchPhase: announced | Yes, as "coming soon" | No |
launchPhase: pre_order | Yes | Only on the pre-order path (below) |
launchPhase: available, tradingState: open | Yes | Yes |
tradingState: paused | Yes | Yes (see below) |
tradingState: discontinued | No | No |
isArchived: true | No | No |
Pre-orders. A pre_order product is orderable when your company has the pre-order
capability (GET /whoami capabilities.preorderEnabled) and its Content Owner has not opted out
of Seller API pre-orders. The order reserves keys and delivers them at release: see the
pre-order recipe; how it delivers depends on the call that
placed it (pre-orders). Otherwise an order for it is
refused with PRODUCT_NOT_SELLABLE, and details.reason says why: PREORDER_NOT_OPEN or
PREORDER_CLOSED (outside the pre-order window), PREORDER_DISABLED (no capability, or the
Content Owner opted out), or LIFECYCLE_NOT_LIVE
(error reference). The same code appears in
readinessBlockers on GET /allocations when sellable is false for lifecycle reasons.
A paused product stays listed, and the order path does not refuse it today: an order for a
paused product is accepted like any other. Treat paused as the Content Owner's signal to stop
selling, and hide the product until it reads open again.
A paused allocation is different: it is not orderable. POST /orders answers 400 with
details.allocationResolve: NO_ACTIVE_ALLOCATION and a message that says the allocation is
paused. POST /orders/preview answers the same on contract date 2026-12-01 and later; earlier
dates answer 404 ALLOCATION_INACTIVE. Nothing in the request can change that; the allocation is
sellable again when the Content Owner resumes it, which allocation.updated tells you. A paused
agreement answers 403 CONTRACT_NOT_ACTIVE instead
(error reference).
Content owners can mark a release Unlisted. For stores nothing changes: an unlisted release you
have access to reports tradingState: open; a release you have no share for is not in your
catalog.
GET /products?status= filters on an older single field (draft, active, discontinued,
archived) and is deprecated: every product you can see reads active there. Filter with
launchPhase= and tradingState= instead; both take comma-separated values.
Regions, platforms and countries#
Three vocabularies describe where and on what a SKU sells. Only one of them is a standard.
Countries are ISO 3166-1 alpha-2 codes in upper case (US, DE, JP) everywhere in the
API: territory prices, allowedCountries, GET /availability?countryCode=, footprint, and the
salesCountryCode you declare on an order. Key every decision on the country.
Regions are named groups of countries. A region code is Avrix's own vocabulary, not a standard, and it comes from one of two places:
- Avrix's reference regions. Many follow the regions the platform holders use for their own
stores, so they overlap: a German buyer is in
EU,NOE,NIN_EU_AU,SIEE,XB_EU,XboxandWWat once. - Regions a Content Owner defines for its own catalog. Their codes are chosen by that Content
Owner and can appear on your catalog next to the reference ones. Two Content Owners can use the
same code;
GET /regionsmerges them under that code and lists every country either one covers.
| Code | Name |
|---|---|
WW | Worldwide |
NA | North America |
LATAM | Latin America |
EU | Europe |
MEA | Middle East & Africa |
APAC | Asia Pacific |
Mainland-China | Mainland China |
NOA, NIN_AMERICAS | Americas |
NOE, NIN_EU_AU | Europe + Australia |
NIN_SEA | Southeast Asia |
NCL, NCL - Asia, NSW_ASIA | Asia |
NCL-Japan, NSW_JAPAN | Japan |
SIEA, SIEE, SIEJ, SIEJA-ASIA, SIEJA-JAPAN | Platform-holder store regions |
XB_EU, Xbox | Xbox Europe, Xbox Worldwide |
The table is the reference set at the time of writing; it can grow. Do not hard-code it, and do
not infer a region's countries from its name: read allowedCountries for each region from
GET /regions (the regions of the SKUs you hold an allocation for, complete in one response) or
GET /regions/{code}. A release can sell in fewer countries than its region lists; what an order
checks is releases[].allowedCountries on GET /products/{productId}. The regions[] summary on
a GET /products row is for display: its code can be null for a region without one.
Platforms are stable lower-case codes with a display name and a family, listed by
GET /platforms: steam, epic, ps4 and ps5 (playstation), xbox_one and
xbox_series (xbox), switch and switch_2 (nintendo) today. GET /platforms carries a
version that moves when the list changes; cache it for an hour and validate platformCode
values against it rather than against a list in your code. GET /products?platform= takes the
same codes.
Common mistakes#
Building the catalog from /products alone. Lists SKUs you cannot deliver: a shared SKU
without a sellable allocation fails at checkout. The most common and most costly defect.
Trusting the catalog sellable decoration. It is cached and can lag. Allocations are
authoritative.
Ignoring tombstones. removed entries must be delisted, not just left to expire.
Caching preview prices. A preview price is valid for the open cart, not for your database. Refresh at the final pay click.
Calling /allocations per product page. It is a checkout-authority endpoint (catalog rate
class, ~60s cache TTL). Sync it on a schedule and read from your mirror. See
Caching and fairness.
Advancing the cursor before applying the batch. A crash mid-apply then silently skips the delta.
Using GET /products?updatedSince= as your only delta. It is a metadata and lifecycle delta.
Price changes never move a product's updatedAt; they arrive on GET /catalog/changes as
changedFields: ["pricing"] and as sku.pricing_updated.
Assuming added / updated / removed top-level arrays. The wire shape is
data.changes[] with a type discriminant. Match OpenAPI, not older draft examples.
Next steps#
- Sellable SKU readiness: readiness blockers in depth
- Order preview: the pre-charge fulfilability gate
- Order lifecycle: after the buyer picks a SKU
- Webhook guide: event-driven refresh
- Error reference: catalog and pricing errors