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 readable id | GET /api/seller/v1/orders?orderReadableId=ord_… |
| Key-pull history | 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 |
| Invoices | GET /api/seller/v1/finance/invoices |
| 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 — escalate; keys are not recoverable from
GET. Prefer webhook replay / delivery audit, then support with
requestId. - 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 /transactions) 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; pullGET /finance/invoiceswhen invoice intake is part of your close. - 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.