Integrators arriving from platforms with explicit price list GUID style objects benefit from naming Avrix economics clearly:
- Authoritative commerce rule sits in BMA terms, allocations, and SKU visibility — not copy-pasted list prices alone.
- Retailer-visible read models expose pricing views derived from catalog + contracts.
Nothing in Seller API contradicts BMA; terminology below helps partners cache and explain prices without weakening contract truth.
Three layers (keep mentally separate)#
| Layer | Meaning | Typical API |
|---|---|---|
| List / storefront price (RRP-style) | What the catalog editor published for shopper display when rows exist — may be sparse | GET /products/{id}/pricing — list price arrays may be empty legitimately (30-minute quickstart) |
| Wholesale / settlement economics | What you owe the publisher and how API sales reconcile | GET /allocations, finance/reporting (Partner runbook) |
| Declared retail checkout evidence | What you attest the end-buyer paid (audit + risk) | integrationOrderContext (Integration recipes) |
Which price is which (checkout)#
At order time, do not conflate buyer retail with the unit price Avrix validates:
- Buyer retail — shopper-facing amount in
integrationOrderContext(salesPriceGrossMinor/salesPriceNetMinor, minor units). - Wholesale / catalog echo — preview
unitPriceCentssent back asexpectedUnitPriceCentsorexpectedWholesaleUnitPriceCentson POST /orders. - Minor units — all money fields are integers in minor units, each with a
currencyExponentnext to its currency code (2for USD,0for JPY,3for KWD); see Money fields.
Which cost applies depends on the business model of the allocation, and pricePerKeyCents has one
meaning across every surface that carries it (GET /allocations, catalog sharedSkus[],
expand=pricing): null means there is no wholesale price, and it is never 0.
| Business model | Your cost | pricePerKeyCents |
|---|---|---|
api | The Content Owner's share of the sale price, net of the consumer VAT you declare. The sale price is the territory list price less any approved promotion: preview unitPriceCents quotes it (promotion applied) and you bind it with expectedUnitPriceCents. The share is a term of your agreement, fixed on each sale at commit, so no catalog field carries it; each committed sale states it (economics on GET /orders, settlement on GET /finance/api-sales). See Pricing | Always null (with currencyCode and currencyExponent) |
wholesale, pre_order | The contract price on the allocation, never changed by a promotion | The price, with its currency and exponent; null until the grant is priced (and then it is not sellable) |
complimentary | Nothing — the keys are free | Always null |
Full checkout flow: Order preview.
Partners should never reconcile publisher invoices from GET …/pricing alone when wholesale differs from list.
Pricing “view” terminology (recommended)#
Informally describe partner pricing surface as the combination of:
- GET /products + incremental sync — what SKUs/products are eligible under active connection + BMA.
GET /products/{id}/pricing— regional list rows when authored.- GET /allocations — your wholesale/unit economics tied to SKU keys you can sell.
That tuple acts like a virtual price list conditioned on BMA — no separate GUID unless we add one in a future version.
Alignment with checksum / snapshot#
Large-catalog partners pair:
- GET /catalog/checksum or GET /catalog/snapshot (OpenAPI contract) — structural/eligibility deltas cheaply (Caching & fairness); both return
changesCursor, your change-feed position, which moves on every change including prices, GET /catalog/changes?cursor=— the delta feed; a territory price change arrives aschangedFields: ["pricing"]and never moves a product'supdatedAt, soGET /products?updatedSince=is a metadata delta, not a pricing one,- GET /products + cursor — row-level metadata deltas,
- Allocation pulls — when wholesale terms or pool changes matter.
Treat pricing view cache invalidation as the maximum of the change-feed cursor, webhook sku.pricing_updated / allocation.* / product.updated, and controlled sync windows.
POST /orders/preview (read-only checkout assist)#
Order preview documents the estimated totals and fulfillment type preview. It is authoritative for strict validation paths (e.g. bulk strict) regarding readable issues, but remains a projection layered on BMA + pools.
Common industry pattern mapping#
| Common pattern | Avrix equivalent |
|---|---|
| “Price list on connection GUID” | Virtual view — allocations + SKU + visible products under BMA |
| “Promotions already merged into GET prices” | List rows + deals/promotions product flows where applicable (/promotions/...), plus settlement truth in finance APIs |
Future platform work could add GET …/pricing-snapshot-style aggregates only if BMA remains authoritative and snapshot versioning is explicit (ETag / checksum / contract revision id).
Related reading#
| Doc | Topic |
|---|---|
| 30-minute quickstart | “Three layers” short table |
| Sellable SKU readiness | When a SKU is checkout-ready |
| Partner runbook | Finance reads and reconciliation |