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:
| Gate | Meaning |
|---|---|
| BMA | An active business master agreement (and governing MCA where required) between vendor and seller |
| Share | The vendor shared the SKU into your catalog scope (catalog + orders) |
| Allocation | You have capacity (GET /allocations → sellable: true) |
| Territory pricing | The 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#
- Retail. You charge the buyer through your PSP. You own the receipt, taxes presentation, and refund decision.
- 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#
- Refund the buyer at your PSP first when the retail sale must be undone.
- Call Avrix (POST /refunds or POST /keys/return) to quarantine keys and adjust finance.
- 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#
- Overview — golden path and four-gates diagram
- Finance and settlement — finance API surfaces
- Catalog and allocations — sellability gates in detail
- Data handling — what evidence you should retain