> ## Documentation Index
> Fetch the complete documentation index at: https://finance.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Order Flow

> How orders work on Aries end-to-end: the order types you can place, the single endpoint that places them, the order lifecycle, and where to watch live status updates over WebSocket.

This is the **map of the Orders module**. It explains, in plain English, what kinds of orders you can place, how the platform decides which kind you meant, what happens to an order after you submit it, and how to follow its status in real time. The following pages drill into each individual order type with copy-paste request and WebSocket examples.

<Note>
  **One endpoint places every order.** You always `POST /v1/orders`. You never pick the order *type* in the URL — the platform infers it from the fields you send (see [How the order type is decided](#how-the-order-type-is-decided)). This is why the per-type pages all hit the same endpoint with a different body.
</Note>

***

## The two halves of trading on Aries

Placing an order is a **request/response** action over REST. But an order is not "done" when the REST call returns — it then lives a life on the exchange (working, partially filling, filling, getting cancelled, etc.). You watch that life over a **WebSocket**.

```mermaid theme={null}
sequenceDiagram
    participant App as Your App
    participant REST as REST API
    participant WS as Account WebSocket

    App->>WS: 1. Connect, authenticate, subscribe to "account"
    WS-->>App: Snapshot (current orders, positions, balance)
    App->>REST: 2. POST /v1/orders (place an order)
    REST-->>App: Accepted — returns clOrdId + initial status
    WS-->>App: 3. account.order event — NEW
    WS-->>App: account.order event — PARTIALLY_FILLED
    WS-->>App: account.order event — FILLED
```

So a robust trading app does **both**, in this order:

1. **Subscribe first** to the [Account Updates WebSocket](/websockets/account-updates) — authenticate and subscribe to the `account` topic for your `accountId`. You get a snapshot of current orders, positions, and balance right away, and won't miss any update that fires the moment you place.
2. **Then place** the order over `POST /v1/orders`. The response is an acknowledgement, not a fill — it confirms the order was *accepted* and returns the `clOrdId` you use to track, cancel, or replace it.
3. **Watch it resolve** on the WebSocket. State changes arrive as `account.order` events — `NEW → PARTIALLY_FILLED → FILLED`, or terminal `REJECTED`/`CANCELED`/`EXPIRED`. These come **only** over the socket; REST never sends a second response.

In short: **REST acts on an order; the WebSocket tells you what happened to it.**

***

## Order types you can place

Aries supports four **order types** (how the order is priced and triggered) across three **asset shapes** (equity, single option, multi-leg option).

### By pricing / trigger

| Type           | What it does                                                            | Required price fields | Guide                                                      |
| -------------- | ----------------------------------------------------------------------- | --------------------- | ---------------------------------------------------------- |
| **Market**     | Fills immediately at the best available price. No price guarantee.      | none                  | [Market order](/api-reference/orders/market-order)         |
| **Limit**      | Fills only at your price or better. Price guarantee, no fill guarantee. | `price`               | [Limit order](/api-reference/orders/limit-order)           |
| **Stop**       | Dormant until the stop price is touched, then becomes a market order.   | `stopPrice`           | [Stop order](/api-reference/orders/stop-order)             |
| **Stop-Limit** | Dormant until the stop price is touched, then becomes a limit order.    | `stopPrice` + `price` | [Stop-limit order](/api-reference/orders/stop-limit-order) |

### By instrument

| Shape                 | How you express it                                                     | Guide                                                        |
| --------------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------ |
| **Equity**            | No `legs` array — just a `symbol`.                                     | All four type pages above                                    |
| **Single-leg option** | Exactly **1** entry in `legs`.                                         | [Single-leg option](/api-reference/orders/single-leg-option) |
| **Multi-leg option**  | **2–4** entries in `legs` (verticals, calendars, ratio spreads, etc.). | [Multi-leg option](/api-reference/orders/multi-leg-option)   |

<Info>
  Any of the four pricing types can apply to equities or single options. Multi-leg option orders in practice use **Market** or **Limit** (a limit price on a spread is the *net* debit/credit across all legs).
</Info>

***

## How the order type is decided

You never send a field called "this is an equity order." Instead:

* **No `legs` → equity order.** The top-level `symbol` is the stock/ETF.
* **1 leg → single-leg option order.**
* **2–4 legs → multi-leg option order.**

The pricing type comes from the `type` field (`MARKET`, `LIMIT`, `STOP`, `STOP_LIMIT`), and the price fields you must include depend on it. Each per-type page shows the exact body.

<Warning>
  **Time-in-force is restricted for options.** Equity orders accept `DAY`, `GTC`, `IOC`, and `FOK`. Orders that carry `legs` (any option order) only accept **`DAY`** or **`GTC`** — sending `IOC`/`FOK` on an option order is rejected.
</Warning>

***

## Anatomy of a place-order request

Every order — equity or option — shares this core. The per-type pages only change which optional fields are present.

| Field              | Required    | Description                                                                              |
| ------------------ | ----------- | ---------------------------------------------------------------------------------------- |
| `tradingAccountId` | yes         | The trading account placing the order.                                                   |
| `symbol`           | yes         | The instrument symbol (underlying symbol for options).                                   |
| `side`             | yes         | `BUY`, `SELL`, `SELL_SHORT`, or `BUY_TO_COVER`.                                          |
| `type`             | yes         | `MARKET`, `LIMIT`, `STOP`, or `STOP_LIMIT`.                                              |
| `qty`              | yes         | Quantity as a decimal string (e.g. `"100"`).                                             |
| `timeInForce`      | yes         | `DAY`, `GTC`, `IOC`, `FOK` (options: `DAY`/`GTC` only).                                  |
| `price`            | conditional | Limit price. Required for `LIMIT` and `STOP_LIMIT`.                                      |
| `stopPrice`        | conditional | Trigger price. Required for `STOP` and `STOP_LIMIT`.                                     |
| `legs`             | conditional | 1–4 option legs. Presence makes it an option order.                                      |
| `clientId`         | no          | Your own correlation identifier, echoed back.                                            |
| `currency`         | no          | 3-letter currency code; defaults to USD.                                                 |
| `exDestination`    | no          | Routing hint (`MNGD`). Managed routing is applied automatically; you normally omit this. |

<Note>
  All monetary and quantity values are sent and returned as **JSON strings**, not numbers, to preserve decimal precision. Send `"150.50"`, not `150.5`.
</Note>

***

## What you get back

A successful `POST /v1/orders` returns an acknowledgement, not a fill. The key fields:

| Field                  | Meaning                                                                                            |
| ---------------------- | -------------------------------------------------------------------------------------------------- |
| `success`              | Whether the order was accepted.                                                                    |
| `clOrdId`              | The client order ID. **Track the order by this** and use it as `origClOrdId` to cancel or replace. |
| `status`               | Initial status — usually `PENDING_NEW` or `NEW`.                                                   |
| `cumQty` / `leavesQty` | Filled vs. remaining quantity (usually `0` / full at acknowledgement).                             |
| `avgPrice`             | Average fill price (fills as they happen).                                                         |
| `ordRejReason`         | Populated only if the order was rejected.                                                          |
| `transactTime`         | Server timestamp.                                                                                  |

Everything after this — the actual fills — comes over the WebSocket.

***

## The order lifecycle

Orders move through a well-defined set of states. You'll see these as the `ordStatus` field on `account.order` WebSocket events.

```mermaid theme={null}
stateDiagram-v2
    [*] --> PENDING_NEW: POST /v1/orders
    PENDING_NEW --> NEW: exchange accepts
    PENDING_NEW --> REJECTED: bad params / no buying power
    NEW --> PARTIALLY_FILLED: some qty executes
    NEW --> FILLED: all qty executes
    PARTIALLY_FILLED --> FILLED: remainder executes
    NEW --> PENDING_CANCEL: you cancel
    PENDING_CANCEL --> CANCELED
    NEW --> PENDING_REPLACE: you replace
    PENDING_REPLACE --> NEW: replace accepted (new clOrdId)
    NEW --> EXPIRED: DAY order unfilled at close
    FILLED --> [*]
    CANCELED --> [*]
    REJECTED --> [*]
    EXPIRED --> [*]
```

| Status             | Meaning                                                                   |
| ------------------ | ------------------------------------------------------------------------- |
| `PENDING_NEW`      | Submitted, not yet accepted by the exchange.                              |
| `NEW`              | Live and working on the book.                                             |
| `PARTIALLY_FILLED` | Some quantity executed; rest still working.                               |
| `FILLED`           | Fully executed. Terminal.                                                 |
| `PENDING_CANCEL`   | Cancel requested, awaiting confirmation.                                  |
| `CANCELED`         | Cancelled. Terminal.                                                      |
| `PENDING_REPLACE`  | Replace requested, awaiting confirmation.                                 |
| `REJECTED`         | Refused (bad params, halted symbol, insufficient buying power). Terminal. |
| `EXPIRED`          | Hit its time-in-force limit without filling. Terminal.                    |

See the full status and field-enum reference on the [Account Updates WebSocket](/websockets/account-updates#ordstatus-values) page.

***

## Where to watch and listen for updates

All order status changes flow over the **Account Updates WebSocket**, on the `account` topic, as events named `account.order`.

1. Connect to `wss://api.aries.com/v1/accounts/ws`.
2. Authenticate within 5 seconds with your access token.
3. Subscribe to the `account` topic with your `accountId`.
4. Receive an initial snapshot (current open orders, positions, balance), then a live stream of `account.order` events as your orders change.

The per-type pages ([Limit order](/api-reference/orders/limit-order), etc.) show the exact subscribe message and the order-event payload for that type. For the complete WebSocket protocol — authentication, all topics, reconnection, and every field — see the [Account Updates WebSocket](/websockets/account-updates) reference.

<Note>
  **If the connection drops.** A dropped socket means you may have missed events while disconnected. On reconnect: re-authenticate, re-subscribe to the `account` topic, and use the snapshot the server returns to reset your view. To be sure nothing was missed, also reload working orders over REST from [Today's Orders](/api-reference/accounts/list-active-orders) and reconcile against your local state before resuming.
</Note>

***

## Modifying and cancelling

Two more endpoints round out the module:

<CardGroup cols={2}>
  <Card title="Replace (modify) an order" icon="pen" href="/api-reference/orders/update-order">
    `POST /v1/orders/replace` — change price, quantity, or time-in-force on a working order. Each replace returns a **new** `clOrdId` you must use for the next replace.
  </Card>

  <Card title="Cancel an order" icon="ban" href="/api-reference/orders/cancel-order">
    `POST /v1/orders/cancel` — cancel a working or partially-filled order by `origClOrdId`. Any quantity already filled is preserved.
  </Card>
</CardGroup>

<Note>
  **Preview before you place.** `POST /v1/orders/preview` accepts the exact same body as place-order and returns estimated cost, commission, buying-power impact, fees, and any warnings — without sending the order. Use it to show a confirmation screen. See [Preview Order](/api-reference/orders/preview-order).
</Note>

***

## Next steps

<CardGroup cols={2}>
  <Card title="Market order" icon="bolt" href="/api-reference/orders/market-order">
    The simplest order. Buy or sell now at the best available price.
  </Card>

  <Card title="Limit order" icon="tag" href="/api-reference/orders/limit-order">
    Set your price. Includes the full REST + WebSocket round-trip.
  </Card>

  <Card title="Single-leg option" icon="layer-group" href="/api-reference/orders/single-leg-option">
    Buy or sell one call or put.
  </Card>

  <Card title="Multi-leg option" icon="diagram-project" href="/api-reference/orders/multi-leg-option">
    Verticals, calendars, and ratio spreads in a single order.
  </Card>
</CardGroup>