Statuses
State transitions
placed → pending → executing → filled → settled. Not every order passes through pending; if no prerequisites need to be resolved, the order can move directly from placed to executing.
An order can be cancelled from placed, pending, or executing, but not after it’s been filled.
How an order reaches settled
1
You place the order
You send a
POST request with the instrument, side, and either cash_amount (buy) or quantity (sell). We validate the request, check that the instrument is tradable, verify the account has sufficient funds or units, reserve the cash or units, and submit the order for execution. The order starts at placed.2
The order becomes pending (sometimes)
If the order is waiting on a prerequisite (for example, a price feed update or a pre-trade compliance check) it moves to
pending. Many orders skip this step entirely.3
The order starts executing
Once submitted to our execution infrastructure, the order moves to
executing. At this point, the order is actively being worked.4
The order fills
When execution completes, the order moves to
filled. Trades are recorded against the order, and the traded_quantity and traded_notional fields are updated. For buy orders, a position is created or increased. For sell orders, the position decreases.5
The order settles
After all trades settle, the order moves to
settled. This is the final resting state for a successful order. The account’s cash balances and positions reflect the settled amounts.How an order gets cancelled
An order can be cancelled at any point before it fills:- By the system: We’ll cancel an order if validation fails during processing (e.g. the instrument stops trading, or the account is suspended), or if execution fails for a reason that can’t be retried.
- During execution: If the order is
executing, cancellation depends on whether trades have already been recorded. If no trades have been executed, the order can be cancelled.
There is no cancel-order endpoint in the API. Orders are cancelled by our execution infrastructure when they can’t be filled, or by our operations team when needed. You’ll be notified via the
order.cancelled webhook event.Terminal states
An order is considered complete when it reaches one of these terminal states:
Your integration should handle both. Don’t assume every order will eventually settle; always implement a path for cancellations.
Webhook events
We fire an event whenever an order changes status. Subscribe to webhooks for real-time updates. In the sandbox environment, see Testing for which events each test order produces.
Related trade events:
Event payloads don’t carry the order data inline. Instead, they include a
resource object with the order ID so you can fetch the latest state:
resource.id to call the Retrieve order endpoint and get the order’s current state. This ensures you’re always working with the latest data, even if events arrive out of order.
Webhook delivery is at-least-once; your handler may receive the same event more than once. Use the event ID or
Webhook-Id header to deduplicate.