Sellable SKU readiness

Which endpoint is authoritative for checkout-ready SKUs, and sellableOnly filtering.

Authoritative endpoint#

GET /allocations — use the sellable flag. Catalog endpoints alone are not the sellable set.

The merge rule. A SKU is sellable when GET /allocations lists it with sellable: true, and only then. That flag already requires an active share and a live product, so an allocation without a share is not sellable (readinessBlockers carries NO_SKU_SHARE) and a shared SKU without an allocation row is not sellable either. The catalog adds metadata only: join the two on the SKU id, which is skuId on an allocation row and id on a sharedSkus[] entry. The catalog guide gives the full algorithm.

When paginating allocations/products, follow meta.nextCursor until null (limit is at most 100). Large catalogs should prefer incremental GET /catalog/changes?cursor= and checksum drift detection over one-shot full mirrors that stop early.

For storefront mirrors that only need checkout-ready SKUs, pass sellableOnly=true:

# The sellable set is GET /allocations rows with sellable: true (limit <= 100; follow meta.nextCursor).
# The snapshot adds metadata: join allocation.skuId to data[].sharedSkus[].id.
curl -s "$AVRIX_BASE_URL/api/seller/v1/allocations?sellableOnly=true&limit=100" -H "Authorization: Bearer $AVRIX_API_KEY"
curl -s "$AVRIX_BASE_URL/api/seller/v1/catalog/snapshot" -H "Authorization: Bearer $AVRIX_API_KEY"

That filters to readiness sellable: true rows. Note: page size may be shorter than limit because filtering happens after readiness computation — always follow meta.nextCursor until null.

Presentation endpoints (GET /products, GET /catalog/snapshot) now decorate each sharedSkus[] row with the same readiness stack:

FieldMeaning
sellableCheckout-ready under current grants/share/lifecycle/pricing
readinessBlockersMachine codes when not sellable
pricePerKeyCents / currencyCode / currencyExponentAdvisory wholesale cost of your grant (wholesale / pre_order). null = no wholesale price, never 0 — always null under businessModel: api, where the cost is a share of the territory list price (GET /products/{id}/pricing, preview unitPriceCents)

Still re-check POST /orders/preview / allocations at commit — catalog sellability can lag grants by a cache window on snapshot.

Predicate stack#

A SKU is sellable when all hold:

  1. Product lifecycle live (not draft, not discontinued, not archived)
  2. Active allocation for the seller
  3. Active share
  4. Active contract authority for the connection
  5. Pricing ready — territory catalog price under the API business model
  6. Commit-time price binding — expectedUnitPriceCents is required on commercial commits (echo the catalog list price from preview)

Catalog presentation vs transact (intentional)#

SurfaceLifecycle behavior
GET /products, GET /catalog/snapshotMay list announced / pre-live products for storefront merchandising.
GET /allocations sellableAuthoritative checkout readiness — includes PRODUCT_NOT_SELLABLE when not live.
POST /orders, preview, pull, export, commitReject non-live products (PRODUCT_NOT_SELLABLE); details.reason / launchPhase / preorderStart / preorderEnd / releaseDate / recommendedAction say why and when the same SKU becomes sellable.
Preorder success metadataSuccessful pre-order pulls may still return preorder / release dates for fulfillment UX — that is not a bypass of the live-product gate for immediate key pulls.

Do not treat catalog list visibility as commit authority; always merge allocations + preview.

Tombstones#

GET /catalog/changes returns added | updated | removed events per seller. Page it with the opaque cursor (since stays supported for older clients). Prefer this over updatedSince alone for mirror correctness.

Archive and full delist emit removed. An unshare emits removed when it ends your access to the product, unless another agreement still shares the product. 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 the availability facet and its skuId: refetch GET /products/{productId} and re-read GET /allocations (sellable) for those SKUs; a SKU the product no longer lists (a 404 on a SKU refetch) is no longer shared with you, so remove it from your listing. Release/SKU-level delists emit updated with the availability facet too: the listing survives but sellability changed, so re-read GET /allocations. See Catalog and allocations for the full emission table.

Webhook payloads#

Persisted webhook deliveries and GET /events do not include plaintext keys. Persist keys from the synchronous POST /orders / POST /keys/pull response. GET /orders never returns key plaintext — see Webhooks and Order preview.

What links here

Published guides that link to this page.

Search docs

Search documentation…