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:
| Field | Source |
|---|---|
orderReference | Your checkout / OMS id |
Idempotency-Key | Generated before POST /orders |
| Preview unit price / commitment token | POST /orders/preview |
Avrix response type and identifiers | POST /orders response |
keyIds | POST /orders response (authoritative) |
| PSP payment reference | Your payment processor |
| Last known webhook event id | Delivery headers |
Canonical reads#
| Need | Call |
|---|---|
| Everything settled, one cursor | GET /api/seller/v1/activity?from=…&to=… (sale / refund / chargeback / pull / reveal with signed stockMovement, promo, counterparty, economics) |
| Order by your reference | GET /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 history | GET /api/seller/v1/keys/pulls (older path GET /api/seller/v1/transactions) |
| Missed webhook deliveries | GET /api/seller/v1/webhooks/{id}/deliveries (+ replay) |
| Catalog drift | GET /api/seller/v1/catalog/changes?since= + /catalog/checksum |
| Finance overview | GET /api/seller/v1/finance/summary |
| Sale lines | GET /api/seller/v1/finance/api-sales |
| Monthly reports and their exchange rates | GET /api/seller/v1/finance/reports, GET /api/seller/v1/finance/reports/{reportId} |
| Invoices | GET /api/seller/v1/finance/invoices, GET /api/seller/v1/finance/invoices/{invoiceId} |
| Payments you owe and made | GET /api/seller/v1/finance/payments |
| What one payout settled | GET /api/seller/v1/finance/invoices/{invoiceId}/reconciliation |
| Refund / chargeback status | GET /api/seller/v1/refunds |
GET /orders returns aggregates (fulfilled[], preOrderActive[]) and never returns plaintext
keys. Design your recovery paths accordingly.
Recommended job (orders)#
Run on a schedule (for example every 5–15 minutes):
- Select local orders in an uncertain or awaiting-webhook state older than your timeout.
- For each, call
GET /orders?orderReference=…. - If Avrix shows fulfilment and you lack keys locally — call
POST /orders/recover-keyswith theorderReference. It returns the live keys already sold under the reference and never pulls new inventory.GET /ordersand webhook replay never carry key plaintext. See the Key recovery runbook. - 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.
- 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):
- Pull operational truth: for each local commercial day (or window), list
GET /orders(and/orGET /keys/pulls) keyed byorderReference. - Pull the settlement feed:
GET /activity?from=…&to=…(paginate withcursor;format=csvfor spreadsheets). SumstockMovementperorderReference— a delivered-then-refunded key nets to zero.GET /finance/api-salesremains available as the sale-line view. - Match rows on
orderReference/keyId. Investigate orphans (Avrix sale without local order, or local capture without Avrix sale). - Check
GET /finance/summaryfor outstanding balances and report posture (currentPeriod.activityTotalsis the running month, per vendor and currency, and equals the ledger'smeta.balancesfor the same period). For the closed months, pullGET /finance/reportsandGET /finance/invoices?updatedSince=when invoice intake is part of your close. - Match payments:
GET /finance/paymentsgives each invoice's amount and payment reference; oncepaymentStateispaid,GET /finance/invoices/{invoiceId}/reconciliationlists 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 date2026-12-01and later the route answers409 CONFLICTwithdetails.reason: RECONCILIATION_NOT_AVAILABLE, earlier dates404. - Align refunds and chargebacks:
GET /refundsvs your PSP dispute ledger; quarantine viaPOST /refundswhen Avrix has not yet been told. - Do not invent payout dates from this API — settlement timing follows your commercial agreement.