Finance & settlement

What is recorded, settled, and invoiced after API sales.

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:

RecordPurpose
Order / pull aggregatesOperational reconciliation via GET /orders, transactions
API sale linesWholesale sale at contracted terms for reporting
Promo provenanceinitialSalePriceCents (list) next to salePriceCents (billed) plus promo (sourceType, sourceId) when a settlement-affecting promotion discounted the line — see Promotions
Buyer country evidencecustomerRegionCode (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 evidenceFrom 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 statusSet 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:

RuleWhat decides itWhat you see when it fails
Four declarations are requiredintegrationOrderContext.salesCountryCode, salesPriceGrossMinor, salesTaxRatePercent, salesChannel on every API catalog order, in sandbox and production alikeSALES_COUNTRY_REQUIRED, TAX_DECLARATION_REQUIRED, SALES_CHANNEL_REQUIRED, before a key is delivered
The footprintThe 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 rateFOOTPRINT_COUNTRY_NOT_DECLARED, FOOTPRINT_CURRENCY_NOT_DECLARED, each with details.fixItUrl
The deductible rate is cappedUnder 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 declaredNothing is refused. settlement.rateReason on the finance line says which branch applied, and the sale carries a vat_country_not_corroborated warning
A rate below the reference settles as declared, flaggedDeclare 5 percent on a Dutch sale and 5 percent is deducted: the platform never deducts VAT you did not charge. The sale carries vat_declared_rate_below_expected on the order response, the preview settlement.warnings, and every finance row, so a mis-configured store shows up on the first sale rather than on a statementRefused only where the agreement says so: the API agreement term vat_declaration_policy is warn by default; under refuse_below_reference the sale is refused on preview and commit with 422 VAT_DECLARATION_BELOW_REFERENCE (details.declaredRatePercent, expectedRatePercent, countryCode) before any key is delivered. GET /whoami shows each Content Owner's policy under vatDeclarationPolicyByPublisher. Countries with a sub-national reference are never refused
Tax-exclusive countries deduct nothingWhere the buyer's country prices tax on top (US, CA), tax was never inside the SRP and nothing is deducted, whatever you declaredsettlement.rateReason: tax_exclusive_country
Currency and channel are termsThe 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 rateCURRENCY_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.

CaseYou declaredBuyer countryEvidenceRate appliedNetVATYour shareOwner share
Corroborated19%DE (19%)Buyer IP agrees19% (corroborated)504195815123529
Declared above the reference21%DE (19%)Buyer IP agrees19% (corroborated, warning vat_declared_rate_above_expected)504195815123529
Declared below the reference5%NL (21%)Buyer IP agrees5% (corroborated, warning vat_declared_rate_below_expected)571328617143999
Not corroborated19%DE (19%)Buyer IP says FR19%: the lower of 19% declared and your store's 21%, applied as declared (declared_within_store_cap)504195815123529
Not corroborated, high-rate country27%HU (27%)No signal21%: capped at your store's rate (fallback_store_country)4958104114873471
Tax-exclusive8.25%USBuyer IP agrees0% (tax_exclusive_country)5999018004199

settlement.rateReason values. corroborated: the buyer country is evidenced and its reference rate capped the declaration. declared_within_store_cap: not corroborated, and the declared rate was at or under your store country's rate, so it applied as declared. fallback_store_country: not corroborated, and your store country's rate lowered the declared rate. fixed_store_country: the agreement settles every sale at your store country's rate (vat_basis: store_country). subnational_declared: a country without one national rate (the ceiling caps the declaration). tax_exclusive_country: tax is added on top in the buyer's country and nothing is deducted. Sales settled before 2026-09-24 read fallback_store_country in both uncorroborated cases.

The fifth 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.

Settlement warnings. What the calculator noticed but did not refuse over is returned as warnings[] on POST /orders, POST /orders/commit, each fulfilled POST /orders/bulk line and POST /keys/pull, previewed under settlement.warnings on POST /orders/preview, and persisted on the sale row so GET /finance/api-sales, GET /activity and GET /transactions return the same codes next to COUNTRY_MISMATCH:

CodeMeaning
vat_declared_rate_below_expectedYou declared a rate below the reference rate for the buyer's country. The sale settled at the rate you declared (an agreement on refuse_below_reference refuses such a sale instead)
vat_declared_rate_above_expectedYou declared a rate above the reference rate; the deduction was capped at the reference
vat_declared_rate_above_ceilingSub-national country: the declaration exceeded the ceiling and was capped
vat_country_not_corroboratedThe buyer country could not be confirmed; the cap was your store country's rate
vat_anonymizer_flagThe buyer connection was anonymised; corroboration was withheld
vat_price_includes_tax_mismatchYour priceIncludesTax disagreed with how the buyer's country prices
vat_declaration_arithmetic_mismatchYour gross, net, tax amount and rate did not agree with each other

Invoicing cadence. whoami.settlement reports your effective mode. invoiceWithinDays is currently always null:

JSON
{
  "settlement": { "mode": "automated_invoice", "invoiceWithinDays": null }
}

Avrix does not issue the invoice for the vendor. Approving a monthly sales report accrues the vendor's share into the running balance between you and that vendor; the vendor then issues its monthly invoice to you 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". What you can rely on per invoice is on the invoice itself: paymentTermsDays (from your agreement) and dueAt.

Avrix settlement is not your retail PSP settlement.

What is invoiced#

Each month, for each vendor you sell for, money moves in one direction: you pay the vendor its share of your sales. Avrix records the sales, builds the monthly report, and keeps the running balance between you and the vendor; the vendor issues the invoice; you pay it. Avrix takes its commission from the vendor, on a separate invoice that is not addressed to you and does not appear in your API.

The documents follow the sales in four steps:

  1. Sale. Each API sale is recorded the moment the order settles. It appears at once on GET /finance/api-sales, on the period's statement, on the ledger and in currentPeriod on GET /finance/summary.
  2. Report. After the month closes, the period's sales are gathered into one monthly report per vendor (report.ready). Read it with GET /finance/reports/{reportId}: totals, the exchange rates it froze and where it stands (confirmation). Its lines are on GET /finance/reports/{reportId}/lines. You confirm an API-sales report, or submit a revenue-share report, in the console; the vendor then approves it.
  3. Invoice. The vendor invoices the approved report's balance. invoice.issued fires and the invoice appears on GET /finance/invoices; GET /finance/invoices/{invoiceId} gives its lines (one per balance movement it bills), its payment, disputes, history and the document, which GET /finance/invoices/{invoiceId}/document downloads. Its status says whether it is payable now or waits for the commission document. Past dueAt unpaid it becomes overdue (invoice.overdue); it stays payable. If it is wrong, dispute it in the console (invoice.disputed); the vendor's answer is invoice.dispute_updated.
  4. Payment and payout. GET /finance/payments lists what you owe per invoice and how it stands (unpaid, in_progress, paid, reversed), with the reference your transfer must carry. When your payment is recorded, by any rail, invoice.paid and payout.file_ready fire, and GET /finance/invoices/{invoiceId}/reconciliation returns the reconciliation file for that payout: every balance movement the invoice settles and, under each one, every API sale it covers (order reference, key id, gross, VAT, net and the vendor, seller and platform shares). The movement amounts add up to the payout total in the payment currency, so the file ties to the bank line first and to individual sales second. Sale amounts stay in the sale currency, with the rate the report line converted at. format=csv gives one row per sale and writes movementAmountCents on the first row of each movement only, so the column sums to the payout total; its last two columns give the exponent of the payment and sale currencies. The same file is downloadable from the invoice page in the console.

Between steps 1 and 3 the invoice list is empty. That is expected, and both routes say so: GET /finance/summary carries a notices entry API_SALES_NOT_YET_REPORTED, and an empty first page of GET /finance/invoices carries meta.notices INVOICES_FOLLOW_APPROVAL. Each notice points at the statement for the period. Reconcile the running month on the statement or the ledger, and the closed months on reports and invoices.

Subscribe to report.ready, invoice.issued, invoice.overdue, invoice.disputed, invoice.dispute_updated, invoice.paid and payout.file_ready to automate accounting intake. (invoice.created is the pro-forma invoice of an allocation, a different document.) Exact timing is agreement-dependent. Every one of these events carries the id the read endpoints take.

Who pays whom: one month, worked through#

You sell 100 keys of one vendor's game in October through the API, at EUR 20.00 each, in a country where you declared 21 percent VAT included in the price; your agreement gives you 30 percent of the net. Each sale is split on its own: gross 2000, VAT 347, net 1653, your share 496, the vendor's share 1157 (minor units).

StepWhat happensWhere you read itAmount (EUR, minor units)
Sales100 sales, gross 200000, VAT 34700, net 165300GET /finance/ledger?period=2026-10 meta.balances, GET /finance/summary currentPeriod.activityTotalsyour share 49600, vendor share 115700
ReportOctober report for the vendor, built 1 NovemberGET /finance/reports/{reportId}: totals.publisherShareCents 115700, confirmation.state
ConfirmationYou confirm the report in the console; the vendor approves itconfirmation.state moves awaiting_seller, awaiting_vendor, approved
InvoiceThe vendor issues its invoice for the approved balance, payable in 30 daysGET /finance/invoices/{invoiceId}: kind: vendor_payable, subtotalCents 115700, lines[] naming the report115700 plus any tax the vendor charges you
PaymentYou pay by bank transfer with the invoice's payment referenceGET /finance/payments: paymentState unpaid, then paid; settledAtamountCents equals the invoice total
Payout fileThe payment clearsGET /finance/invoices/{invoiceId}/reconciliation: 100 sales under the report movementmovements sum to the invoice total

Your 49600 is never paid to you: you collected the whole 200000 from your buyers, remit the VAT, and keep your share. A refund in November is a negative movement on the ledger in November, and lands on a later invoice as a negative line.

Invoice states#

statusMeaningPayable
awaiting_commission_documentIssued; waits for the commission document before payment opensNo
payableOpen for paymentYes
overduePast dueAt unpaid (invoice.overdue)Yes
disputedYou contested it; payment paused until the vendor answersNo
paidYour payment was recorded (invoice.paid)No
supersededReplaced by a corrected invoice: pay supersededByInvoiceId insteadNo
sent, cancelled, creditedInvoices of the earlier per-report billing modelAs before

Filter the list with status, kind, invoiceType, publisherCompanyId, reportMonth, issuedFrom / issuedTo and updatedSince. Treat an unknown status as not payable and read the invoice again.

Credit notes and corrections#

  • A corrected invoice names the invoice it replaces in replacesInvoiceId (also on its invoice.issued event); the replaced invoice has status: superseded and supersededByInvoiceId. Pay the corrected one only.
  • A credit note (invoiceType: credit_note) carries a positive total: the type, not the sign, says the money comes back to you.
  • A refund or chargeback after an invoice is not an edit of that invoice. It is a negative movement that the next invoice bills as a negative line (lines[].amountCents below zero).

Which endpoint answers which question#

QuestionRead
What did I sell, sale by sale?GET /finance/api-sales, GET /activity
What do I owe this vendor so far this month?GET /finance/ledger?period= (meta.balances), GET /finance/summary (currentPeriod.activityTotals)
Which report covers last month, and do I need to act on it?GET /finance/reports (confirmation.state, nextActor, deadline)
Which exchange rate was used?GET /finance/reports/{reportId} (fx) and the report lines (exchangeRate)
Which invoices are open, and when are they due?GET /finance/invoices?status=payable,overdue
What exactly does this invoice bill?GET /finance/invoices/{invoiceId} (lines)
Where is the PDF?GET /finance/invoices/{invoiceId}/document
Have I paid it, and with which reference?GET /finance/payments, or payment on the invoice
Which sales does this payment settle?GET /finance/invoices/{invoiceId}/reconciliation
Month-end close in one fileGET /finance/statements?period=

The finance vocabulary in one place: a sale becomes activity on the ledger; a month of it becomes a report; the approved report becomes a balance the vendor invoices; your payment settles the invoice, and the payout file lists what it settled.

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

kindstockMovementSource
sale+1API-model sale line (one per key)
refund, chargeback−1The reversal entry for that line, at the instant the money moved (the same row statements count as refundedCents)
reinstatement+1A won chargeback restoring a reversed line (statements: reinstatedCents)
pull+1Custody-only delivery (wholesale, revenue share, complimentary), priced from the allocation
reveal0Keyless redemption viewed / activated / redeemed

Summing economics.unitPriceCents over the sale, refund, chargeback and reinstatement entries of a period equals that period's statement net (grossSalesCents − refundedCents + reinstatedCents), per currency: the feed and the statement read the same ledger rows. A refund / chargeback entry is the recorded settlement reversal, which is written shortly after the refund answers (the same background step that adjusts the statement); GET /finance/api-sales flips adjustmentStatus at once, so poll it for the refund's acceptance and the feed for its money.

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.

The feed needs seller:finance:read, the same scope as the finance routes below. Keys issued with seller:products:read for it keep working; that name is deprecated for the feed in the scope matrix.

The ledger#

GET /api/seller/v1/finance/ledger is the money half of the activity log, in ledger form: the sale, refund, chargeback and reinstatement entries of one window, oldest first, each with its signed amounts (grossCents, publisherShareCents, sellerShareCents, platformFeeCents) and balanceAfter, the running totals of its currency up to and including that entry.

  • Window. period=YYYY-MM (a UTC calendar month, the window a statement covers) or from and to (at most 366 days). Balances start at zero at the start of the window and run per currency; there is no balance across currencies or per counterparty.
  • Ties to the statement. meta.balances carries the closing balances of the whole window on every page. For a calendar month they equal activityTotals of GET /finance/statements?period= for the same month, field for field (grossSalesCents, refundedCents, reinstatedCents, netSalesCents and the shares and fee). Both read the same ledger rows; a nightly check alarms if they ever disagree.
  • Refunds and chargebacks are their own negative entries at the instant the money moved, never an edit of the sale entry. An entry's amounts never change once returned.
  • Paging. Follow meta.nextCursor while meta.hasMore is true, keeping the same window; balances continue exactly from page to page. Balances are computed on each request, so an entry recorded late with an earlier timestamp moves the balances after it.
  • currency narrows the ledger to one currency, and format=csv downloads the page with the next cursor in X-Next-Cursor. Every finance list pages the same way (Lists and pagination).

Finance endpoints#

Under /api/seller/v1/finance/* (scope seller:finance:read):

EndpointUse
GET /api/seller/v1/finance/summaryOutstanding balances per publisher relationship, draft sales-report count, recent monthly reports, the running month's API sales (currentPeriod, with activityTotals per vendor and currency, equal to the ledger's meta.balances) and notices. A report's total is totalNetRevenueMinor in minor units with currencyExponent; totalNetRevenue, the same total in major units, is its older form
GET /api/seller/v1/finance/api-salesPaginated API sale lines (from / to, orderReference, cursor); CSV export where offered (format=csv), whose last three columns are promoSourceType, promoSourceId and initialSalePriceCents
GET /api/seller/v1/finance/api-sales/{transactionId}One API sale line by its id
GET /api/seller/v1/finance/statements?period=YYYY-MMMonth-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/ledgerMoney ledger for a window (period=YYYY-MM or from / to): sale, refund, chargeback and reinstatement entries with running balances per currency; closing balances equal the statement's activityTotals (The ledger)
GET /api/seller/v1/finance/reportsMonthly sales reports, one per vendor and month, with totals and confirmation state; filter by status, modelType, reportMonth, publisherCompanyId
GET /api/seller/v1/finance/reports/{reportId}One report: totals in minor units, the exchange rates it froze (fx), attested rates, confirmation state and deadline, disputes
GET /api/seller/v1/finance/reports/{reportId}/linesThe report's lines, paged: sale amounts in the sale currency, shares in the report currency
GET /api/seller/v1/finance/invoicesThe invoices you owe (issued after report approval; an empty first page explains itself in meta.notices); filters as in Invoice states. Each names both of its numbers: platformInvoiceNumber (the number Avrix gives it, also sent as invoiceNumber) and supplierInvoiceNumber (the number on the publisher's own document, null when there is none), the same two values invoice.issued and invoice.paid carry
GET /api/seller/v1/finance/invoices/{invoiceId}One invoice: lines, payment, payment records, disputes, document and history
GET /api/seller/v1/finance/invoices/{invoiceId}/documentA five-minute download link for the invoice document
GET /api/seller/v1/finance/paymentsYour payment of each invoice: amount, method, reference, state, settlement date
GET /api/seller/v1/finance/invoices/{invoiceId}/reconciliationReconciliation file for one payout: every movement and API sale the invoice settles, with order reference, key id, gross, VAT, net and shares; format=csv downloads it. Final once paymentState is paid (payout.file_ready). An invoice without a settlement (reconciliationAvailable: false) answers 409 CONFLICT with details.reason: RECONCILIATION_NOT_AVAILABLE on contract date 2026-12-01 and later, 404 before

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; meta carries the same value with hasMore and nextUrl, like every list, and the CSV sends it as X-Next-Cursor. 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. The statement CSV carries the same columns as the api-sales CSV for each line: its first twelve columns are unchanged, and currencyExponent, the key, report and settlement columns follow. On contract date 2026-12-01 and later the statement refuses an unknown format and reports a bad limit against limit, and an infrastructure failure answers 503 or 504 with Retry-After, like the other finance routes.

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/*:

EndpointUse
GET /api/seller/v1/keys/pullsPaginate with cursor; filter orderReference, from, to as needed. Each row's keyPullId names the pull and transactionId the sale row it produced, the id GET /finance/api-sales/{transactionId} reads. GET /transactions is the older path of the same list

Refund / chargeback adjustment status is on the refunds read model (not under /finance/*):

EndpointUse
GET /api/seller/v1/refundsList adjustments (refund | chargeback)
GET /api/seller/v1/refunds/{refundId}Single adjustment
POST /api/seller/v1/refundsDeclare 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 the adjustment's status (chargeback_open, chargeback_lost, chargeback_won) on GET /refunds; a sale row of GET /finance/api-sales carries the same value as refundStatus, and the ledger's own value as adjustmentStatus. 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#

ResponsibilityOwner
Charge / refund the buyerYou, at your PSP
Quarantine keys + finance adjustmentAvrix (POST /refunds, POST /keys/return)
End-consumer tax filingYou / 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.

What links here

Published guides that link to this page.

Search docs

Search documentation…