## Preview Orders **post** `/v1/accounts/{account_id}/orders/preview` Preview the impact of orders without submitting them. For each order the engine evaluates every pre-trade risk check and projects the account's balances and positions as if the order were fully filled — at the limit price for limit orders and at the current reference price for market orders. Orders are evaluated independently: they do not see each other's projected fills. Nothing is submitted and no account state changes. The response carries one result per requested order, in request order. When the request contains more than one order, every order must carry a unique `id`, which is echoed on its result. An order that cannot be previewed gets an `error` on its own result without affecting the rest of the batch; the response is still `200 OK` — per-order outcomes live only in the rows, and non-2xx statuses are reserved for request-level failures (invalid batch, authorization, engine unavailable). ### Path Parameters - `account_id: number` ### Body Parameters - `preview: array of NewOrderRequest` - `order_type: RequestOrderType` Type of order - `"MARKET"` - `"LIMIT"` - `"STOP"` - `"STOP_LIMIT"` - `"TRAILING_STOP"` - `"TRAILING_STOP_LIMIT"` - `quantity: string` Quantity to trade. For COMMON_STOCK: shares (may be fractional if supported). For OPTION (single-leg): contracts (must be an integer) - `side: Side` Side of the order - `"BUY"` - `"SELL"` - `time_in_force: RequestTimeInForce` Time in force - `"DAY"` - `"GOOD_TILL_CANCEL"` - `"IMMEDIATE_OR_CANCEL"` - `"FILL_OR_KILL"` - `"GOOD_TILL_DATE"` - `"AT_OPEN"` - `"AT_CLOSE"` - `id: optional string` Optional client-provided unique ID (idempotency). Required to be unique per account. - `expires_at: optional string` The timestamp when the order should expire (UTC). Required when time_in_force is GOOD_TILL_DATE. - `extended_hours: optional boolean` Allow trading outside regular trading hours. Some brokers disallow options outside RTH. - `instrument_id: optional InstrumentIDOrSymbol` Instrument ID (UUID) or symbol (equity ticker or OSI option symbol). Either `symbol` or `instrument_id` must be provided. - `limit_offset: optional string` Limit offset for trailing stop-limit orders (signed) - `limit_price: optional string` Limit price (required for LIMIT and STOP_LIMIT orders) - `position_intent: optional RequestPositionEffect` Optional open/close intent for this order. When omitted, the platform determines the position effect. - `"OPEN"` - `"CLOSE"` - `stop_price: optional string` Stop price (required for STOP and STOP_LIMIT orders) - `strategy: optional OrderStrategy` Optional execution strategy. One of `SOR`, `VWAP`, `TWAP`, or `DMA`. Defaults to `SOR`, the only strategy OTC common-stock orders support. `VWAP` and `TWAP` are supported only on `MARKET` and `LIMIT` orders, and `DMA` only on `LIMIT` orders; all three require `DAY` time-in-force. `VWAP`, `TWAP`, and `DMA` do not support `extended_hours`. - `Type object { type }` Smart Order Router. Routes the order to the best available venue(s). - `type: "SOR"` Execution strategy type. - `"SOR"` - `object { type, end_at, start_at }` Volume-Weighted Average Price. Works the order to track the volume-weighted average price over the execution window. - `type: "VWAP"` Execution strategy type. - `"VWAP"` - `end_at: optional string` UTC timestamp (RFC 3339) by which to finish working the order. Defaults to market close. - `start_at: optional string` UTC timestamp (RFC 3339) at which to begin working the order. Defaults to the time the order is received. - `object { type, end_at, start_at }` Time-Weighted Average Price. Spreads execution evenly across the execution window. - `type: "TWAP"` Execution strategy type. - `"TWAP"` - `end_at: optional string` UTC timestamp (RFC 3339) by which to finish working the order. Defaults to market close. - `start_at: optional string` UTC timestamp (RFC 3339) at which to begin working the order. Defaults to the time the order is received. - `object { destination, type }` Direct Market Access. Routes the order straight to the named venue. - `destination: string` Venue code the order is routed to. - `type: "DMA"` Execution strategy type. - `"DMA"` - `symbol: optional string` Trading symbol. For equities, use the ticker symbol (e.g., "TSLA"). For options, use the OSI symbol (e.g., "TSLA 250117C00190000"). Either `symbol` or `instrument_id` must be provided. - `trailing_offset: optional string` Trailing offset amount (required for trailing orders) - `trailing_offset_type: optional TrailingOffsetType` Trailing offset type (PRICE or PERCENT_BPS) - `"PRICE"` - `"BPS"` ### Returns - `data: OrderPreviewEntryList` - `object { preview, id }` The order was previewed successfully. - `preview: OrderPreview` The projected impact of the order. - `account_id: number` The account the order was previewed for. - `amount: OrderPreviewAmount` Monetary size of the previewed order. - `gross_amount: string` Total cash impact of the order before estimated fees and commissions. - `net_amount: string` Total cash impact of the order after estimated fees and commissions. - `buying_power: OrderPreviewDelta` Buying power before and after the order. - `after: string` The value with the previewed order also fully filled. - `before: string` The value before the order, as the risk engine evaluates it: the account's open orders are projected as filled. - `change: string` The previewed order's isolated impact: `after - before`. - `currency: string` Currency for all monetary values. - `equity: OrderPreviewDelta` Account equity before and after the order. - `errors: array of OrderPreviewError` Risk-check errors that would prevent the order from being accepted. Empty when the order would pass every pre-trade risk check. - `description: string` Human-readable description of the error. - `metadata: map[string]` Structured details for the error (stringified values), e.g. required and available amounts, and `leg_index`/`leg_symbol` for multileg leg errors. - `type: string` Stable error code. - `margin_details: OrderPreviewMarginDetails` Margin requirements and excess before and after the order. - `initial_margin_excess: OrderPreviewDelta` Initial margin excess. - `initial_margin_requirement: OrderPreviewDelta` Initial margin requirement. - `maintenance_margin_excess: OrderPreviewDelta` Maintenance margin excess. - `maintenance_margin_requirement: OrderPreviewDelta` Maintenance margin requirement. - `overnight_margin_excess: OrderPreviewDelta` Overnight margin excess. - `overnight_margin_requirement: OrderPreviewDelta` Overnight margin requirement. - `positions: array of OrderPreviewPosition` Positions in the traded instruments before and after the order. - `instrument_id: string` The instrument's identifier. - `quantity: OrderPreviewDelta` Net position quantity before and after the order. - `symbol: string` The instrument's symbol. - `id: optional string` The client-provided `id` of the order this entry belongs to, echoed from the request. Always present when the request contains more than one order, since ids are required there. - `object { error, id }` The order could not be previewed. Shaped exactly like the top-level `error` object on rejected submissions. - `error: APIError` Why this order's preview failed. - `code: number` The error code is used to identify the nature of the error. It corresponds to an HTTP status code. - `message: string` A human-readable message providing more details about the error. - `details: optional array of map[unknown]` Additional error details, if any. This can include structured information such as field violations or error metadata. - `id: optional string` The client-provided `id` of the order this entry belongs to, echoed from the request. Always present when the request contains more than one order, since ids are required there. ### Example ```http curl https://api.clearstreet.com/v1/accounts/$ACCOUNT_ID/orders/preview \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $API_KEY" \ -d '[ { "order_type": "LIMIT", "quantity": "100", "side": "BUY", "time_in_force": "DAY", "id": "preview-1", "expires_at": "2025-10-15T16:00:00.000000000Z", "extended_hours": true, "instrument_id": "x", "limit_offset": "0.50", "limit_price": "100.00", "position_intent": "OPEN", "stop_price": "52.00", "strategy": { "type": "SOR" }, "symbol": "AAPL", "trailing_offset": "2.00", "trailing_offset_type": "PRICE" }, { "order_type": "LIMIT", "quantity": "10", "side": "BUY", "time_in_force": "DAY", "id": "preview-2", "expires_at": "2025-10-15T16:00:00.000000000Z", "extended_hours": true, "instrument_id": "x", "limit_offset": "0.50", "limit_price": "250.00", "position_intent": "OPEN", "stop_price": "52.00", "strategy": { "type": "SOR" }, "symbol": "TSLA", "trailing_offset": "2.00", "trailing_offset_type": "PRICE" } ]' ``` #### Response ```json { "data": [ { "id": "preview-1", "preview": { "account_id": 19816, "amount": { "gross_amount": "10000.00", "net_amount": "10000.00" }, "buying_power": { "after": "190000.00", "before": "200000.00", "change": "-10000.00" }, "currency": "USD", "equity": { "after": "100000.00", "before": "100000.00", "change": "0.00" }, "errors": [], "margin_details": { "initial_margin_excess": { "after": "95000.00", "before": "100000.00", "change": "-5000.00" }, "initial_margin_requirement": { "after": "5000.00", "before": "0.00", "change": "5000.00" }, "maintenance_margin_excess": { "after": "97500.00", "before": "100000.00", "change": "-2500.00" }, "maintenance_margin_requirement": { "after": "2500.00", "before": "0.00", "change": "2500.00" }, "overnight_margin_excess": { "after": "95000.00", "before": "100000.00", "change": "-5000.00" }, "overnight_margin_requirement": { "after": "5000.00", "before": "0.00", "change": "5000.00" } }, "positions": [ { "instrument_id": "a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8", "quantity": { "after": "100", "before": "0", "change": "100" }, "symbol": "AAPL" } ] } }, { "error": { "code": 400, "message": "Security not found: BADSYM" }, "id": "preview-2" } ], "metadata": { "request_id": "d3e5b1a2-8c4f-4b6e-9d2a-1f0c9b8a7654" } } ```