How Avrix works

BMA, share, allocation, territory pricing, and how money moves.

The commercial model has three layers partners often conflate: permission to fulfil, per-sale records, and settlement / invoicing. This page separates them so checkout engineers and finance teams do not talk past each other.

Who needs this#

Partner engineers and commercial contacts who need the money and permission model before designing checkout or finance reconciliation.

TL;DR#

  • Fulfilment requires four gates (BMA, share, allocation, territory pricing) — refusals here are not invoices.
  • Retail (you ↔ buyer at your PSP) and wholesale (you ↔ Avrix ↔ vendor) are independent streams.
  • Each successful pull creates a per-sale wholesale record; settlement timing follows your agreement.
  • Avrix never auto-refunds your PSP — refund the buyer first, then call Avrix to quarantine keys.

Permission: four gates#

Before Avrix will deliver entitlements, these gates must pass:

GateMeaning
BMAAn active Business Model Agreement (and the governing master agreement, MCA, where required) between vendor and seller
ShareThe vendor shared the SKU into your catalog scope (catalog + orders)
AllocationYou have capacity (GET /allocations → sellable: true)
Territory pricingThe buyer’s country has a valid catalog / contracted price for the API model

Failed gates return structured errors (for example inactive contract, territory not allowed, product not sellable). These refusals are not the same as monthly invoicing.

Money: two independent streams#

Diagram
  1. Retail. You charge the buyer through your PSP. You own the receipt, taxes presentation, and refund decision.
  2. Wholesale. Each successful Avrix fulfilment records a sale at contracted terms for partner settlement.

Avrix does not invoice the end consumer or collect retail tax. Declared retail evidence on the order (integrationOrderContext) supports disputes and reconciliation — it is not a tax engine.

Per-sale records#

When a pull succeeds under an API business model allocation, Avrix records the sale for reporting and finance APIs. Refunds and returns stamp adjustment status so clawed-back lines are excluded from later aggregation.

Settlement primer#

Settlement is the periodic process that turns per-sale wholesale records into reports, vendor approval, invoices, and payouts under your commercial agreement.

What the API guarantees today:

  • A durable wholesale sale (or adjustment) line when fulfilment or quarantine succeeds.
  • Coarse posture discovery via GET /api/seller/v1/whoami → integrationReadiness (for example prepaid wallet vs invoice / report paths) and per-partner flags on GET /partners.
  • Finance reads under /api/seller/v1/finance/* when your key has finance scopes.

What varies by agreement (not a universal API SLA):

  • How often reports run, who approves them, and when payouts land.
  • Whether you settle via prepaid wallet, invoice, or another contracted mode.

Returns and PSP refunds#

  1. Refund the buyer at your PSP first when the retail sale must be undone.
  2. Call Avrix (POST /refunds or POST /keys/return) to quarantine keys and adjust finance.
  3. Avrix never auto-refunds your PSP.

Common mistakes#

  • Treating a CONTRACT_NOT_ACTIVE / territory error as a billing outage.
  • Expecting Avrix to reverse a Stripe/PSP charge after NO_AVAILABLE_KEYS.
  • Summing retail and wholesale as if they shared one ledger currency or timeline.

Next steps#

What links here

Published guides that link to this page.

Search docs

Search documentation…