Authoritative endpoint#
GET /allocations — use the sellable flag. Merge with catalog lists yourself (or via a
generated client); catalog endpoints alone are not the sellable set.
When paginating allocations/products, follow meta.nextCursor until null. Large catalogs
should prefer incremental GET /catalog/changes?since= and checksum drift detection over
one-shot full mirrors that stop early.
For storefront mirrors that only need checkout-ready SKUs, pass sellableOnly=true:
# Fetch both, then keep SKUs present in catalog AND sellable:true on allocations
curl -s "$AVRIX_BASE_URL/api/seller/v1/catalog/snapshot" -H "Authorization: Bearer $AVRIX_API_KEY"
curl -s "$AVRIX_BASE_URL/api/seller/v1/allocations" -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:
| Field | Meaning |
|---|---|
sellable | Checkout-ready under current grants/share/lifecycle/pricing |
readinessBlockers | Machine codes when not sellable |
pricePerKeyCents / currencyCode / currencyExponent | Advisory wholesale-cost summary when a grant exists |
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:
- Product lifecycle live (not draft, not discontinued, not archived)
- Active allocation for the seller
- Active share or full-catalog BMA scope
- Active contract authority for the connection
- Pricing ready — territory catalog price under the API business model
- Commit-time price binding —
expectedUnitPriceCentsis required on commercial commits (echo the catalog list price from preview)
Catalog presentation vs transact (intentional)#
| Surface | Lifecycle behavior |
|---|---|
| GET /products, GET /catalog/snapshot | May list announced / pre-live products for storefront merchandising. |
GET /allocations sellable | Authoritative checkout readiness — includes PRODUCT_NOT_SELLABLE when not live. |
| POST /orders, preview, pull, export, commit | Reject non-live products (PRODUCT_NOT_SELLABLE); details.reason / launchPhase / preorderStart / preorderEnd / releaseDate / recommendedAction say why and when the same SKU becomes sellable. |
| Preorder success metadata | Successful 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?since= returns added | updated | removed events per seller. Prefer this over updatedSince alone for mirror correctness.
Archive, full delist, and unshare that ends your catalog access all emit removed. An unshare that leaves the product browse-visible (whole-catalog sharing) and release/SKU-level delists emit updated with the availability facet instead — 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.