Reconciliation

Tie storefront orders to Avrix aggregates and resolve discrepancies.

Tie your storefront orders to Avrix records so uncertain outcomes, missed webhooks, and support tickets resolve from facts — not guesswork.

Example#

curl -s -X GET "https://api.avrix.io/api/seller/v1/orders?orderReference=store-order-10432" \
  -H "Authorization: Bearer $AVRIX_API_KEY"

What to store locally#

For every commercial attempt, persist at least:

FieldSource
orderReferenceYour checkout / OMS id
Idempotency-KeyGenerated before POST /orders
Preview unit price / commitment tokenPOST /orders/preview
Avrix response type and identifiersPOST /orders response
keyIdsPOST /orders response (authoritative)
PSP payment referenceYour payment processor
Last known webhook event idDelivery headers

Canonical reads#

NeedCall
Everything settled, one cursorGET /api/seller/v1/activity?from=…&to=… (sale / refund / chargeback / pull / reveal with signed stockMovement, promo, counterparty, economics)
Order by your referenceGET /api/seller/v1/orders?orderReference=store-order-10432
Order by Avrix id (orderId)GET /api/seller/v1/orders/{orderId} or GET /api/seller/v1/orders?orderReadableId=ord_…
Key-pull historyGET /api/seller/v1/keys/pulls (older path GET /api/seller/v1/transactions)
Missed webhook deliveriesGET /api/seller/v1/webhooks/{id}/deliveries (+ replay)
Catalog driftGET /api/seller/v1/catalog/changes?since= + /catalog/checksum
Finance overviewGET /api/seller/v1/finance/summary
Sale linesGET /api/seller/v1/finance/api-sales
Monthly reports and their exchange ratesGET /api/seller/v1/finance/reports, GET /api/seller/v1/finance/reports/{reportId}
InvoicesGET /api/seller/v1/finance/invoices, GET /api/seller/v1/finance/invoices/{invoiceId}
Payments you owe and madeGET /api/seller/v1/finance/payments
What one payout settledGET /api/seller/v1/finance/invoices/{invoiceId}/reconciliation
Refund / chargeback statusGET /api/seller/v1/refunds

GET /orders returns aggregates (fulfilled[], preOrderActive[]) and never returns plaintext keys. Design your recovery paths accordingly.

Run on a schedule (for example every 5–15 minutes):

  1. Select local orders in an uncertain or awaiting-webhook state older than your timeout.
  2. For each, call GET /orders?orderReference=….
  3. If Avrix shows fulfilment and you lack keys locally — call POST /orders/recover-keys with the orderReference. It returns the live keys already sold under the reference and never pulls new inventory. GET /orders and webhook replay never carry key plaintext. See the Key recovery runbook.
  4. If Avrix has no order and your PSP captured funds — do not create a second order with a new idempotency key until you have replayed the original key and body. See Idempotency and Order lifecycle.
  5. If Avrix fulfilled but your PSP failed — return keys / refund path and refund at your PSP as your policy requires.

Finance reconciliation procedure#

Run on a settlement-relevant cadence (daily or per your agreement — cadence is agreement-dependent):

  1. Pull operational truth: for each local commercial day (or window), list GET /orders (and/or GET /keys/pulls) keyed by orderReference.
  2. Pull the settlement feed: GET /activity?from=…&to=… (paginate with cursor; format=csv for spreadsheets). Sum stockMovement per orderReference — a delivered-then-refunded key nets to zero. GET /finance/api-sales remains available as the sale-line view.
  3. Match rows on orderReference / keyId. Investigate orphans (Avrix sale without local order, or local capture without Avrix sale).
  4. Check GET /finance/summary for outstanding balances and report posture (currentPeriod.activityTotals is the running month, per vendor and currency, and equals the ledger's meta.balances for the same period). For the closed months, pull GET /finance/reports and GET /finance/invoices?updatedSince= when invoice intake is part of your close.
  5. Match payments: GET /finance/payments gives each invoice's amount and payment reference; once paymentState is paid, GET /finance/invoices/{invoiceId}/reconciliation lists every sale the payout settled, and its movement amounts add up to the bank line. The CSV gives the minor-unit exponent of the payment and sale currencies in its last two columns. An invoice without a settlement has no file: on contract date 2026-12-01 and later the route answers 409 CONFLICT with details.reason: RECONCILIATION_NOT_AVAILABLE, earlier dates 404.
  6. Align refunds and chargebacks: GET /refunds vs your PSP dispute ledger; quarantine via POST /refunds when Avrix has not yet been told.
  7. Do not invent payout dates from this API — settlement timing follows your commercial agreement.

See Finance and settlement.

What links here

Published guides that link to this page.

Search docs

Search documentation…