Pricing authority

List vs wholesale vs declared retail — which price binds at checkout.

TopicsCatalog

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)#

LayerMeaningTypical API
List / storefront price (RRP-style)What the catalog editor published for shopper display when rows exist — may be sparseGET /products/{id}/pricing — list price arrays may be empty legitimately (30-minute quickstart)
Wholesale / settlement economicsWhat you owe the publisher and how API sales reconcileGET /allocations, finance/reporting (Partner runbook)
Declared retail checkout evidenceWhat 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 unitPriceCents sent back as expectedUnitPriceCents or expectedWholesaleUnitPriceCents on POST /orders.
  • Minor units — all money fields are integers in minor units, each with a currencyExponent next to its currency code (2 for USD, 0 for JPY, 3 for 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 modelYour costpricePerKeyCents
apiThe 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 PricingAlways null (with currencyCode and currencyExponent)
wholesale, pre_orderThe contract price on the allocation, never changed by a promotionThe price, with its currency and exponent; null until the grant is priced (and then it is not sellable)
complimentaryNothing — the keys are freeAlways null

Full checkout flow: Order preview.

Partners should never reconcile publisher invoices from GET …/pricing alone when wholesale differs from list.

Informally describe partner pricing surface as the combination of:

  1. GET /products + incremental sync — what SKUs/products are eligible under active connection + BMA.
  2. GET /products/{id}/pricing — regional list rows when authored.
  3. 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 as changedFields: ["pricing"] and never moves a product's updatedAt, so GET /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 patternAvrix 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).

DocTopic
30-minute quickstart“Three layers” short table
Sellable SKU readinessWhen a SKU is checkout-ready
Partner runbookFinance reads and reconciliation

What links here

Published guides that link to this page.

Search docs

Search documentation…