Skip to main content
Version: v2

Order Tracking (Polling)

How to follow an order to completion by polling. For push delivery, see Webhooks.

The pattern​

Poll GET /orders/{unique_reference}/ while the order is in a non-terminal status, and stop as soon as it reaches a terminal one.

PhaseStatusesSuggested interval
Awaiting depositINITIAL30–60 s
In flightUNCONFIRMED PAYMENT, PAID, PRE-RELEASE, RELEASED, PENDING KYC, INITIATED REFUND, REFUND FAILED30–60 s
Terminal — stop pollingCOMPLETED, CANCELED, REFUNDED—

Add jitter to intervals and back off (e.g. to 2–5 min) for orders that stay in the same status for hours — PENDING KYC and refund retries can take a while. Full status semantics: Order Lifecycle.

Rules that keep polling correct​

  1. Track by unique_reference, one order at a time. The list endpoint is for backfill/reconciliation, not live tracking — and DeFi orders never appear in it, only in per-order retrieval.
  2. Persist the order mode at creation. Don't rebuild UI state purely from the detail response (why).
  3. Treat unknown statuses as "in flight". New statuses may appear; don't crash or mark the order failed on an unrecognized value.
  4. Stop conditions are terminal statuses, not time. An order past its payment window will transition to CANCELED on its own — keep polling until it does (or the user abandons the page and your backend takes over).
  5. Respect rate limits. Polling many orders from one key at tight intervals can hit throttling — see Errors & Rate Limits. Batch reconciliation belongs on the list endpoint with cursors, not parallel detail calls.

Speeding things up​

After the user confirms they've paid, PATCH the order with marked_as_paid: true and the deposit_transaction hash — crediting starts without waiting for the deposit to be independently detected (Update Order).

Polling individual active orders covers the happy path. Additionally run a periodic sweep (e.g. every 10–15 min) over your locally stored non-terminal references and re-fetch each — this catches orders whose polling loop died with the user's session. CeFi orders can also be cross-checked in bulk via the list endpoint filtered by pair/status.

Next steps​