Catalog & allocations

The four gates that make a SKU sellable, and how to sync them.

TopicsCatalog

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 /allocations answers capacity and sellability.
  • Merge both on the SKU id. A SKU is sellable only when GET /allocations says sellable: 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 unitPriceCents as expectedUnitPriceCents on commit.

The core idea#

Two different questions have two different answers, from two different endpoints:

QuestionEndpointAnswer
What products am I permitted to see?GET /products, GET /catalog/snapshotThe shared catalog
What can I actually sell right now?GET /allocationsYour 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.

Diagram

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 situationIn /products and /catalog/snapshot?In /allocations?Sellable?
Shared and allocatedYesYesYes
Shared, not allocatedYesNoNo
Allocated, not sharedNoYesNo (NO_SKU_SHARE)
NeitherNoNoNo

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.

SurfaceEndpointsUse for
Browse and syncGET /products, GET /catalog/snapshot, GET /catalog/changes, POST /catalog/exportsBuilding and maintaining your local catalog mirror
Rich metadataGET /products/{id}, GET /products/{id}/pricingProduct detail pages: artwork, descriptions, ratings, regional prices
Checkout authorityGET /allocations, GET /availability, POST /orders/previewDeciding 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.

Diagram

Step 1: Cold start#

Pull the full shared catalog once.

Bash
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.

JSON
{
  "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#

Bash
curl -s "https://api.avrix.io/api/seller/v1/allocations?limit=100" \
  -H "Authorization: Bearer avrix_sk_your_key_here"
JSON
{
  "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. readinessBlockers says why (NO_SKU_SHARE when 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).

Bash
curl -s "https://api.avrix.io/api/seller/v1/catalog/changes?cursor=eyJ2IjoxLCJzZXEiOjQxMDB9" \
  -H "Authorization: Bearer avrix_sk_your_key_here"
JSON
{
  "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.

Bash
curl -s "https://api.avrix.io/api/seller/v1/availability/changes?cursor=eyJ2IjoxLCJmZWVkIjoiYXZhaWxhYmlsaXR5Iiwic2VxIjo5MDB9" \
  -H "Authorization: Bearer avrix_sk_your_key_here"
JSON
{
  "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 from GET /products and GET /catalog/snapshot.
  • Unshare: removed when 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 as updated with changedFields: ["availability"] and its skuId and skuCode, the same entry a SKU-level delist writes. Refetch GET /products/{productId} (an unshared SKU is no longer listed, so remove it from your listing; a newly shared one is) and re-read GET /allocations sellable for those SKUs.
  • Release- or SKU-level delist while the product stays live: updated with changedFields: ["availability"]: refetch the product and re-read GET /allocations sellable for 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#

Bash
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:

EventRefresh
product.updatedThe affected product
product.announcedCatalog delta
product.delistedDelist immediately
release.availableCatalog delta
release.date_changedListing dates; notify pre-order buyers
sku.pricing_updatedTerritory pricing for that SKU
sku.sellability_changedBuy button for that SKU (confirm with GET /allocations)
allocation.updatedAllocations
allocation.depletedAllocations: stop selling that SKU
allocation.low_stockAllocations: consider throttling (repeated while low)
allocation.running_lowAllocations: reorder or ask for more keys (once per crossing of your threshold)
allocation.request_decided, allocation.request_cancelledYour 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/commit for a cancelled reservation returns RESERVATION_GONE, and a POST /orders with a cancelled checkoutHoldId fails hold validation.
  • allocation.updated is delivered with reason: "revoked" (or "paused"); stop selling the SKU immediately and treat GET /allocations as 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, setAside keys 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's remaining still caps what you can take; the window guarantees the stock, not extra quota.
  • setAside can be lower than reservedQuantity when 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#

OperationSuggested frequencyNotes
GET /catalog/snapshotCold start and after checksum drift onlyCatalog rate class
POST /catalog/exportsLarge-catalog bootstrap when you want a resumable artifact202 { exportId }; poll GET /catalog/exports/{exportId}
GET /catalog/changesEvery 5–15 minutes, plus on webhookOpaque cursor (or exclusive since); repeat while hasMore
GET /allocationsEvery 5–15 minutes, plus on allocation webhooksCatalog rate class; published cache guidance ~60s
GET /catalog/checksumDailyIntegrity signal: cold-start on change
GET /availabilityAt checkout, not during browsing
POST /orders/previewWhen 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.

CurrencycurrencyExponentWire valueAmount
USD2199919.99 USD
JPY023502350 JPY
KWD365006.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.

FieldMeaningWhere it appears
basePriceCentsThe list price of one SKU in one country: what a sale under the api business model chargesGET /products/{id}/pricing skus[].prices[] and the deprecated release-level prices[], GET /catalog/snapshot?pricing=territory sharedSkus[].territoryPrices[], GET /products/{id} skus[].prices[]
priceCentsThe same list price for one requested country, or the old and new price of a price changeGET /availability?countryCode= price, sku.pricing_updated (top level, previousPricing, newPricing)
srpPriceCentsSuggested retail price in your pricing country (srpCurrencyCode, with srpCurrencyExponent); a browse hint, never a sale priceGET /products and GET /catalog/snapshot sharedSkus[]
pricePerKeyCentsWholesale contract price per key under wholesale / pre_order; null means no wholesale price, never 0, and it is always null under businessModel: apiGET /allocations, catalog sharedSkus[] (with currencyCode and currencyExponent)
listPriceFromCentsLowest list price among the shared offers of a product, in your pricing country; a browse hintGET /products rows (with listPriceCurrencyCode), expand=pricing echo (with listPriceCurrencyExponent)
wholesaleFromCentsLowest priced wholesale / pre_order grant on a product; advisoryGET /products?expand=pricing (with wholesaleCurrencyCode and wholesaleCurrencyExponent)
unitPriceCentsThe binding unit price of a quote or hold; echo it as expectedUnitPriceCents on commitPOST /orders/preview lines[], POST /orders/hold, GET /activity economics
*Minor (grossMinor, netMinor, vatMinor, salesPriceGrossMinor, ...)Settlement and declared-retail amountsintegrationOrderContext (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 readsSale, share, fee, balance and invoice amountsGET /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) or srpPriceCents (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 basePriceCents for that country (GET /products/{id}/pricing, or territoryPrices on a snapshot taken with ?pricing=territory), or price on GET /availability?countryCode=.
  • To charge, read unitPriceCents from POST /orders/preview and 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 seeLikely missing gateWhat to check
Empty partners / no catalog at all1: BMAGET /whoami → hasActiveBma; ask your vendor / Avrix contact
SKU absent from snapshot and allocations2: Share (or no BMA)Vendor share scope; partners list
SKU in catalog, sellable: false, blocker NO_ALLOCATION3: AllocationCapacity grant inactive or never issued
SKU allocated, preview/order fails with CATALOG_PRICE_NOT_SET / territory errors4: Territory pricingBuyer countryCode / salesCountryCode vs catalog price
Catalog shows “coming soon”, commit returns PRODUCT_NOT_SELLABLELifecycle (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.

BlockerGateResolution
NO_SKU_SHARE2The vendor has not shared this SKU with commit authority
NO_ALLOCATION3Shared but no capacity granted / grant inactive
NO_TERRITORY_PRICING4No territory price for the country (API model)
PRODUCT_NOT_SELLABLELifecycleNot transactable: not yet released (outside the pre-order path), discontinued or archived
PRODUCT_EXCLUDED2Product excluded from your share. No longer emitted: scope is the explicit share list.
PAYMENT_NOT_CLEARED3The 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.

FieldValuesQuestion it answers
launchPhaseannounced, pre_order, available (draft is never shown to you)How far the release has come
tradingStateopen, paused, discontinuedWhether the Content Owner is trading it now
isArchivedtrue, falseWhether it has been withdrawn from the catalog

How they combine:

StateListed in catalog feedsOrderable
launchPhase: announcedYes, as "coming soon"No
launchPhase: pre_orderYesOnly on the pre-order path (below)
launchPhase: available, tradingState: openYesYes
tradingState: pausedYesYes (see below)
tradingState: discontinuedNoNo
isArchived: trueNoNo

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, Xbox and WW at 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 /regions merges them under that code and lists every country either one covers.
CodeName
WWWorldwide
NANorth America
LATAMLatin America
EUEurope
MEAMiddle East & Africa
APACAsia Pacific
Mainland-ChinaMainland China
NOA, NIN_AMERICASAmericas
NOE, NIN_EU_AUEurope + Australia
NIN_SEASoutheast Asia
NCL, NCL - Asia, NSW_ASIAAsia
NCL-Japan, NSW_JAPANJapan
SIEA, SIEE, SIEJ, SIEJA-ASIA, SIEJA-JAPANPlatform-holder store regions
XB_EU, XboxXbox 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#

What links here

Published guides that link to this page.

Search docs

Search documentation…