/trading-orders

name: alpaca-broker-trading-orders
description: Place and manage orders on behalf of accounts via the Alpaca Broker API — order creation (qty vs notional, fractional shares, order types/TIF/classes), order status lifecycle, replace/cancel, positions, and trading-account buying power. Use when building trading, recurring-invest, or portfolio flows on Alpaca in any language.

Alpaca Broker API — Trading on Behalf of Accounts

Place, modify, cancel, and track orders for an end-user account, and read positions & buying power. The defining feature of Broker API trading: **`account_id` is in the path** — you act *for* a user account, not your own.

> Read `alpaca-broker-integration` first for base URLs and auth (client-credentials Bearer token; legacy Basic still works). (The standalone Trading API uses `/v2/orders` with no account in the path; everything else here transfers.)

Reference

• Guides: `https://docs.alpaca.markets/docs/orders-at-alpaca`, `https://docs.alpaca.markets/docs/fractional-trading`
• API ref: `https://docs.alpaca.markets/reference/postorder`
• Live schema: `alpaca-docs` MCP → `get-endpoint` title `"Broker API"` path `/v1/trading/accounts/{account_id}/orders`

1. Endpoints

| Method | Path | Purpose | |--------|------|---------| | POST | `/v1/trading/accounts/{id}/orders` | Create order | | GET | `/v1/trading/accounts/{id}/orders` | List orders (filter by `status`, `symbols`, `after`…) | | GET | `/v1/trading/accounts/{id}/orders/{order_id}` | Get order by ID | | GET | `/v1/trading/accounts/{id}/orders:by_client_order_id?client_order_id=…` | Get by your client ID | | PATCH | `/v1/trading/accounts/{id}/orders/{order_id}` | Replace (modify) order | | DELETE | `/v1/trading/accounts/{id}/orders/{order_id}` | Cancel one order (204) | | DELETE | `/v1/trading/accounts/{id}/orders` | Cancel all (207 Multi-Status) | | POST | `/v1/trading/accounts/{id}/orders/estimation` | Cost-estimate an order | | GET / DELETE | `/v1/trading/accounts/{id}/positions[/{symbol_or_asset_id}]` | List / close positions | | GET | `/v1/trading/accounts/{id}/account` | Trading-account details (buying power etc.) |

2. Create-order request

Schema-required: `type` and `time_in_force`. Conditionally required: `symbol`, `side`, and exactly one of `qty`/`notional`.

// notional market buy (dollar-based, fractional)
{ "symbol": "AAPL", "notional": "25.00", "side": "buy", "type": "market", "time_in_force": "day",
  "client_order_id": "your-own-uuid" }

// limit qty sell
{ "symbol": "AAPL", "qty": "3", "side": "sell", "type": "limit", "limit_price": "190.00", "time_in_force": "gtc" }

| Field | Values / notes | |-------|----------------| | `symbol` | required (except `mleg` multi-leg options) | | `qty` | decimal **string**, up to **9 dp**; fractionable only for `market`+`day` per the order schema | | `notional` | decimal **string**, up to **2 dp**. **Mutually exclusive with `qty`** | | `side` | `buy`, `sell` (plus advanced: `sell_short`, …) | | `type` | `market`, `limit`, `stop`, `stop_limit`, `trailing_stop` | | `time_in_force` | `day`, `gtc`, `opg`, `cls`, `ioc`, `fok` | | `limit_price` / `stop_price` | required for limit/stop variants | | `trail_price` / `trail_percent` | one required for `trailing_stop` | | `extended_hours` | bool; only with `type=limit` and TIF `day`/`gtc` | | `client_order_id` | ≤128 chars; **your idempotency key** (auto-generated if omitted) | | `order_class` | `simple` (default), `bracket`, `oco`, `oto`, `mleg` | | `take_profit` / `stop_loss` | `{limit_price}` / `{stop_price, limit_price?}` for bracket/oco/oto | | `position_intent` | `buy_to_open`, `sell_to_close`, … |

**qty XOR notional (verbatim rule):** pass one or the other — supplying both → `400`. In the response, whichever you didn't use comes back `null`.

3. Fractional / notional rules

• **On by default** for all accounts (live + paper).
• Asset must have **`fractionable: true`** (check the Assets API — see `alpaca-broker-market-data`), else `requested asset is not fractionable`.
• **TIF must be `day`** for fractional/notional.
• **Notional** is limited to `market` and `limit` (day); only `limit` for extended hours.
• **No shorting fractional** — all fractional sells are marked long.
• Precision: **2 decimal places for `notional`, 9 for `qty`** (Broker API FAQ, "What is the precision for notional and qty"; the order schema's "2 decimal points" on `qty` is stale). Eligible types: the order schema says fractional `qty` only on `market`+`day`; the Fractional Trading guide also accepts `limit`/`stop`/`stop_limit` at TIF `day` — confirm in sandbox before relying on the wider set.

4. Order status lifecycle

`OrderStatus` (the order object's `status`): `new`, `partially_filled`, `filled`, `done_for_day`, `canceled`, `expired`, `replaced`, `pending_cancel`, `pending_replace`, `accepted`, `pending_new`, `accepted_for_bidding`, `stopped`, `rejected`, `suspended`, `calculated`.

> **Order `status` ≠ trade-event `event`.** The order object's `status` is the enum above. The **SSE trade-update stream** reports a *richer* `event` enum that adds operational events with no Broker order status — `trade_bust`, `trade_correct`, `restated`, `order_cancel_rejected`, `order_replace_rejected`. `held` is both: a trade event, and an `OrderStatus` in the **Trading API** enum though not in the Broker one, so don't assume the two enums match. See `alpaca-broker-sse-events`.

**Terminal:** `filled`, `canceled`, `expired`, `rejected` (and `replaced` for the original order). **Everything else is in-flight.**

**Early-state distinctions (these trip people up):**

• `accepted` — received by Alpaca, not yet routed to a venue (common outside market hours).
• `new` — received **and routed to exchanges**; the usual initial live state.
• `pending_new` — routed but not yet accepted for execution (rare).

An order usually reaches `new` directly; `accepted`/`pending_new` are rare intermediates. **Lesson:** treat `new`/`accepted`/`pend