What Avrix records when you sell, what settlement means, and which finance APIs to call.
Example#
curl -s -X GET "https://api.avrix.io/api/seller/v1/finance/summary" \
-H "Authorization: Bearer $AVRIX_API_KEY"What is recorded#
Each successful commercial fulfilment can produce:
| Record | Purpose |
|---|---|
| Order / pull aggregates | Operational reconciliation via GET /orders, transactions |
| API sale lines | Wholesale sale at contracted terms for reporting |
| Promo provenance | initialSalePriceCents (list) next to salePriceCents (billed) plus promo (sourceType, sourceId) when a settlement-affecting promotion discounted the line — see Promotions |
| Buyer country evidence | customerRegionCode (declared) next to detectedCountryCode (resolved from the buyer IP at pull time), countryMismatch and warnings (COUNTRY_MISMATCH) — also the warning column of the api-sales CSV. See Territory enforcement |
| Declared retail evidence | From integrationOrderContext for disputes — not tax calculation |
Tax metadata (taxMetadata) | Your declared tax amount / rate / inclusivity, echoed back per line with authoritative: false — Avrix never computes tax for you |
| Adjustment status | Set when refunds / chargebacks quarantine keys |
Adjusted lines are excluded from later monthly aggregation so clawbacks do not double-count.
What is settled#
Settlement is the vendor↔seller money path under your agreement — reports, invoices, approvals, and payouts. Discover posture via GET /api/seller/v1/whoami → settlement (and integrationReadiness) plus GET /partners.
The settlement basis of an API sale#
Under an API-model agreement the Content Owner's share is a percentage of the suggested retail price net of the consumer VAT you declare you charged, never of the gross. Five rules decide what "net" is on each sale, and every one of them is a term of the agreement you signed or a declaration you made, not a platform setting:
| Rule | What decides it | What you see when it fails |
|---|---|---|
| Four declarations are required | integrationOrderContext.salesCountryCode, salesPriceGrossMinor, salesTaxRatePercent, salesChannel on every API catalog order, in sandbox and production alike | SALES_COUNTRY_REQUIRED, TAX_DECLARATION_REQUIRED, SALES_CHANNEL_REQUIRED, before a key is delivered |
| The footprint | The countries and currencies you declared you sell in (whoami.footprint, PUT /me/footprint). An order outside it is refused; a sale into a declared country whose buyer country cannot be confirmed settles at your store country's rate | FOOTPRINT_COUNTRY_NOT_DECLARED, FOOTPRINT_CURRENCY_NOT_DECLARED, each with details.fixItUrl |
| The deductible rate is capped | Under vat_basis: purchaser_country_capped the rate deducted is the lower of the rate you declared and the platform's reference rate for the buyer's country when the country is corroborated (checkout attestation or an agreeing buyer IP, and the country is in your footprint). When it is not corroborated, or the connection is anonymised, the cap is your store country's rate instead. Evidence only ever removes trust; it never raises the deduction above what you declared | Nothing is refused. settlement.rateReason on the finance line says which branch applied, and the sale carries a vat_country_not_corroborated warning |
| Tax-exclusive countries deduct nothing | Where the buyer's country prices tax on top (US, CA), tax was never inside the SRP and nothing is deducted, whatever you declared | settlement.rateReason: tax_exclusive_country |
| Currency and channel are terms | The Commercial Schedule states which currencies you may sell in (permitted_sale_currencies) and through which channels (permitted_sales_channels); whoami.permittedCurrenciesByPublisher shows them before you hit one. Settlement converts once, at the period's dated reference rate | CURRENCY_NOT_PERMITTED_BY_TERM, SALES_CHANNEL_NOT_PERMITTED; see Currency and FX |
A sale that cannot be settled (no declared rate, an unknown buyer country, a store with no registered country) is still delivered. It is held out of the statement as quarantined until the fact it needs exists; whoami.integrationReadiness.blockers names a missing store country as STORE_COUNTRY_MISSING.
Worked example
One key, SRP EUR 59.99 (5999 minor), agreement share 30 percent to you, your company registered in the Netherlands (reference rate 21 percent). Shares are taken off the unrounded net, your share is rounded half-up and the Content Owner takes the remainder, so gross equals VAT plus both shares on every line.
| Case | You declared | Buyer country | Evidence | Rate applied | Net | VAT | Your share | Owner share |
|---|---|---|---|---|---|---|---|---|
| Corroborated | 19% | DE (19%) | Buyer IP agrees | 19% (corroborated) | 5041 | 958 | 1512 | 3529 |
| Declared above the reference | 21% | DE (19%) | Buyer IP agrees | 19% (corroborated, warning vat_declared_rate_above_expected) | 5041 | 958 | 1512 | 3529 |
| Not corroborated | 19% | DE (19%) | Buyer IP says FR | 19%: the lower of 19% declared and your store's 21% (fallback_store_country) | 5041 | 958 | 1512 | 3529 |
| Not corroborated, high-rate country | 27% | HU (27%) | No signal | 21%: capped at your store's rate (fallback_store_country) | 4958 | 1041 | 1487 | 3471 |
| Tax-exclusive | 8.25% | US | Buyer IP agrees | 0% (tax_exclusive_country) | 5999 | 0 | 1800 | 4199 |
The fourth row is the cap doing its work: without corroboration the platform will not deduct Hungary's 27 percent on your word alone, and settles as if the sale were made at home. Corroborate the country (an attestation at checkout, or a buyer IP that agrees) and the full 27 percent is deducted. The figures come from the platform's one settlement calculator, the same code that prices the preview, stamps the sale and builds the statement.
Invoicing cadence. whoami.settlement reports your effective mode. invoiceWithinDays is currently always null:
{
"settlement": { "mode": "automated_invoice", "invoiceWithinDays": null }
}
Avrix does not automate invoice issuance. Approving a sales report accrues the share into the running balance, and the vendor raises the commission invoice as a separate, deliberate act. There is therefore no platform-committed invoicing deadline in any mode. The field stays on the wire for compatibility (its schema has been nullable since launch) and is reserved for a future committed SLA; treat null as "no committed invoicing latency". Invoice and payout timing remain agreement-dependent.
Avrix settlement is not your retail PSP settlement.
What is invoiced#
Invoices and sales reports are produced according to your commercial configuration. Subscribe to invoice.created and report.ready when you automate accounting intake. Exact timing is agreement-dependent.
One activity log#
GET /api/seller/v1/activity is the single record to reconcile against: one keyset-pageable feed
at sale grain where every entry carries a signed stockMovement, the counterparty, the promo
reference, the buyer-country evidence (requestedCountry, detectedCountry, warnings) and the
economics (billed and list unit price, shares, fee — negative on reversals).
kind | stockMovement | Source |
|---|---|---|
sale | +1 | API-model sale line (one per key) |
refund, chargeback | −1 | The same line once refunded / chargeback lost, at the adjustment instant |
pull | +1 | Custody-only delivery (wholesale, revenue share, complimentary), priced from the allocation |
reveal | 0 | Keyless redemption viewed / activated / redeemed |
Filter with kinds, from / to, promoId, counterparty, orderReference; format=csv
downloads the same rows. The finance routes below remain as views over the same facts.
Finance endpoints#
Under /api/seller/v1/finance/* (scope seller:finance:read):
| Endpoint | Use |
|---|---|
GET /api/seller/v1/finance/summary | Outstanding balances per publisher relationship, draft sales-report count, recent monthly reports |
GET /api/seller/v1/finance/api-sales | Paginated API sale lines (from / to, cursor); CSV export where offered (format=csv) |
GET /api/seller/v1/finance/statements?period=YYYY-MM | Month-end close: per-currency totals (gross, refunded, net, shares, fees) plus every transaction line for the calendar month; format=csv downloads the lines |
GET /api/seller/v1/finance/invoices | Paginated seller invoices |
For example, a month with 8,000 transactions can be read with
GET /api/seller/v1/finance/statements?period=2026-08&limit=1000. The first response
contains 1,000 lines, totalLineCount: 8000, and full-period activityTotals.
Follow nextCursor with the same period until it is null. All pages preserve the
same financial snapshot for 30 minutes. If the cursor expires, restart without it.
The existing totals field covers returned lines (totalsScope: "returned_lines").
Use activityTotals for full-period sales activity, pendingTotals for activity
awaiting aggregation, and quarantinedTotals for activity requiring review.
Unresolved components in quarantined entries are not final amounts.
approvedSettlements identifies approved reports for the month and their issued
invoices in payment currency. outstandingBalances shows what remains outstanding
across all periods as of generatedAt. Report IDs connect activity to settlements;
invoice IDs can be matched to the invoice list.
[!WARNING] These views describe different stages of the same money. Do not add them together or treat transaction activity as an amount payable. Keep currencies separate.
CSV downloads contain one page. Continue using the
X-Avrix-Statement-Next-Cursor response header; X-Avrix-Statement-Total-Lines
reports the complete line count and X-Avrix-Statement-Truncated indicates more pages.
VAT settlement and reversal entries.
Each API-sale line includes a settlement block with the agreement basis, VAT and net
minor amounts, applied and declared rates, rate reason, evidence rank, and requested
country. Treat these values as the stamped settlement used for the sale; do not
recalculate historical VAT from today's reference rates.
entryType distinguishes ordinary sale rows from negative sale_reversal rows and
positive sale_reinstatement rows. A reversal points to the sale it undoes; a
reinstatement points to that reversal and restores the same stamped amounts after a
won chargeback. When counting units or gross sales, filter to entryType == "sale";
when reconciling net financial movement, include all entry types. Statement
refundedCents and reinstatedCents come from those ledger entries, not from the
original sale's current adjustment status.
Per-key pull history (one row per key pulled) is available outside /finance/*:
| Endpoint | Use |
|---|---|
GET /api/seller/v1/transactions | Paginate with cursor; filter orderReference, from, to as needed |
Refund / chargeback adjustment status is on the refunds read model (not under /finance/*):
| Endpoint | Use |
|---|---|
GET /api/seller/v1/refunds | List adjustments (refund | chargeback) |
GET /api/seller/v1/refunds/{refundId} | Single adjustment |
POST /api/seller/v1/refunds | Declare refund or chargeback with keyIds + reference |
Schemas and filters are defined in the OpenAPI reference.
Chargebacks#
Declare chargebacks through POST /api/seller/v1/refunds with type: "chargeback" (and matching
chargebackReference / keyIds). Track adjustmentStatus values such as chargeback_open,
chargeback_lost, and chargeback_won on GET /refunds. Avrix quarantines keys and stamps
finance lines — it does not fight or settle the dispute at your PSP.
Avrix does not auto-refund your PSP#
| Responsibility | Owner |
|---|---|
| Charge / refund the buyer | You, at your PSP |
| Quarantine keys + finance adjustment | Avrix (POST /refunds, POST /keys/return) |
| End-consumer tax filing | You / your advisors |
On NO_AVAILABLE_KEYS after a successful PSP charge: refund the buyer at your PSP, then stop — do not invent a second Avrix order.
Related#
- How Avrix works
- Reconciliation
- Key return policy
- How your share is protected for what caps the tax deducted before the split, and what it does not cover
- Integration order context for the four required declarations and their error codes
- Currency and FX for permitted currencies, channels and the dated reference rate