--- title: "Preview Orders" method: POST path: "/v1/accounts/{account_id}/orders/preview" tags: ["Orders"] --- # Preview Orders `POST /v1/accounts/{account_id}/orders/preview` ## Request - Base URL: `https://api.clearstreet.com` - URL: `https://api.clearstreet.com/v1/accounts/{account_id}/orders/preview` - Auth: HTTP bearer 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` integer, required ## Request body - OrderSubmissionRequest[] - `expires_at` string, date-time, nullable: The timestamp when the order should expire (UTC). Required when time_in_force is GOOD_TILL_DATE. - `extended_hours` boolean, nullable: Allow trading outside regular trading hours. Some brokers disallow options outside RTH. - `id` string, nullable: Optional client-provided unique ID (idempotency). Required to be unique per account. - `instrument_id` string: Instrument identifier: either an instrument UUID or a symbol (symbol for equities, OSI for options). Non-UUID inputs are resolved server-side. - `limit_offset` string, nullable: Limit offset for trailing stop-limit orders (signed) - `limit_price` string, nullable: Limit price (required for LIMIT and STOP_LIMIT orders) - `order_type` 'MARKET' | 'LIMIT' | 'STOP' | 'STOP_LIMIT' | 'TRAILING_STOP' | 'TRAILING_STOP_LIMIT', required: Strict order-type enum for order submission/replacement requests. - `position_intent` 'OPEN' | 'CLOSE': Client-attested open/close intent for an order. - `quantity` string, required: Quantity to trade. For COMMON_STOCK: shares (may be fractional if supported). For OPTION (single-leg): contracts (must be an integer) - `side` 'BUY' | 'SELL', required: Side of the order (BUY or SELL). - `stop_price` string, nullable: Stop price (required for STOP and STOP_LIMIT orders) - `strategy` union: Optional execution strategy controlling how the order is worked in the market. Omit to use standard routing. One of `SOR`, `VWAP`, `TWAP`, or `DMA`. - object: Smart Order Router. Routes the order to the best available venue(s). - `type` 'SOR', required: Execution strategy type. - object: Volume-Weighted Average Price. Works the order to track the volume-weighted average price over the execution window. - `end_at` string, date-time: UTC timestamp (RFC 3339) by which to finish working the order. Defaults to market close. - `start_at` string, date-time: UTC timestamp (RFC 3339) at which to begin working the order. Defaults to the time the order is received. - `type` 'VWAP', required: Execution strategy type. - object: Time-Weighted Average Price. Spreads execution evenly across the execution window. - `end_at` string, date-time: UTC timestamp (RFC 3339) by which to finish working the order. Defaults to market close. - `start_at` string, date-time: UTC timestamp (RFC 3339) at which to begin working the order. Defaults to the time the order is received. - `type` 'TWAP', required: Execution strategy type. - object: Direct Market Access. Routes the order straight to the named venue. - `destination` string, required: Venue code the order is routed to. - `type` 'DMA', required: Execution strategy type. - `symbol` string, nullable: 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. - `time_in_force` 'DAY' | 'GOOD_TILL_CANCEL' | 'IMMEDIATE_OR_CANCEL' | 'FILL_OR_KILL' | 'GOOD_TILL_DATE' | 'AT_OPEN' | 'AT_CLOSE', required: Strict time-in-force enum for order submission requests. - `trailing_offset` string, nullable: Trailing offset amount (required for trailing orders) - `trailing_offset_type` 'PRICE' | 'BPS': Trailing offset type for trailing stop orders. ## Response `200` Batch evaluated: one result per order, in request order, each carrying either a `preview` or that order's `error` - object - `error` ApiError: A direct mapping of tonic::Status, for use in HTTP responses. - `code` integer, required: The error code is used to identify the nature of the error. It corresponds to an HTTP status code. - `details` object[] - `message` string, required: A human-readable message providing more details about the error. - `metadata` ResponseMetadata, required: Metadata for the response. This will always contain a request ID which can be used to identify the request to Clear Street for tracing, and optionally may include pagination data. - `next_page_token` string, byte, nullable: Base64URL-encoded pagination token - `page_number` integer, nullable: Pagination. Included if this was a GET (list) response - `previous_page_token` string, byte, nullable: Base64URL-encoded pagination token - `request_id` string, required: A unique ID for this request, generated upon ingestion of the request. - `total_items` integer, nullable: Total number of items available (not just in this page). - `total_pages` integer, nullable: Total number of pages available. - `data` OrderPreviewEntry[], required - union - object: One requested order's entry in the batch response. - `preview` OrderPreview, required: The projected impact of an order, as if it were submitted and fully filled. - `account_id` integer, required: The account the order was previewed for. - `amount` OrderPreviewAmount, required: Monetary size of the previewed order. - `gross_amount` string, required: Total cash impact of the order before estimated fees and commissions. - `net_amount` string, required: Total cash impact of the order after estimated fees and commissions. - `buying_power` OrderPreviewDelta, required: Before/after values for one metric, as if the previewed order fully filled. - `after` string, required: The value with the previewed order also fully filled. - `before` string, required: The value before the order, as the risk engine evaluates it: the account's open orders are projected as filled. - `change` string, required: The previewed order's isolated impact: `after - before`. - `currency` string, required: Currency for all monetary values. - `equity` OrderPreviewDelta, required: Before/after values for one metric, as if the previewed order fully filled. - `after` string, required: The value with the previewed order also fully filled. - `before` string, required: The value before the order, as the risk engine evaluates it: the account's open orders are projected as filled. - `change` string, required: The previewed order's isolated impact: `after - before`. - `errors` OrderPreviewError[], required: Risk-check errors that would prevent the order from being accepted. Empty when the order would pass every pre-trade risk check. - `description` string, required: Human-readable description of the error. - `metadata` object, required: Structured details for the error (stringified values), e.g. required and available amounts, and `leg_index`/`leg_symbol` for multileg leg errors. - `type` string, required: Stable error code. - `margin_details` OrderPreviewMarginDetails, required: Margin requirements and excess before and after the previewed order. - `initial_margin_excess` OrderPreviewDelta, required: Before/after values for one metric, as if the previewed order fully filled. - … - `initial_margin_requirement` OrderPreviewDelta, required: Before/after values for one metric, as if the previewed order fully filled. - … - `maintenance_margin_excess` OrderPreviewDelta, required: Before/after values for one metric, as if the previewed order fully filled. - … - `maintenance_margin_requirement` OrderPreviewDelta, required: Before/after values for one metric, as if the previewed order fully filled. - … - `overnight_margin_excess` OrderPreviewDelta, required: Before/after values for one metric, as if the previewed order fully filled. - … - `overnight_margin_requirement` OrderPreviewDelta, required: Before/after values for one metric, as if the previewed order fully filled. - … - `positions` OrderPreviewPosition[], required: Positions in the traded instruments before and after the order. - `instrument_id` string, uuid, required: The instrument's identifier. - `quantity` OrderPreviewDelta, required: Before/after values for one metric, as if the previewed order fully filled. - … - `symbol` string, required: The instrument's symbol. - `id` string, nullable: 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: One requested order's entry in the batch response. - `error` ApiError, required: A direct mapping of tonic::Status, for use in HTTP responses. - `code` integer, required: The error code is used to identify the nature of the error. It corresponds to an HTTP status code. - `details` object[] - `message` string, required: A human-readable message providing more details about the error. - `id` string, nullable: 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. ## Other responses - `400`: Invalid request: empty batch, or missing/duplicate order ids - `403`: Forbidden - `422`: Malformed order request payload - `500`: Internal server error - `503`: Engine unavailable, retry later ## Changes - **2026-10-30** `7e4b278ca27a`: 1 info - endpoint added [Operation history](https://skmtc.dev/clear-street/apis/clear-street-trading-api/changes/v1/accounts/:account_id/orders/preview/post.md) --- [API](https://skmtc.dev/clear-street/apis/clear-street-trading-api.md) - [All operations](https://skmtc.dev/clear-street/apis/clear-street-trading-api/llms.txt) - [OpenAPI document](https://skmtc.dev/clear-street/apis/clear-street-trading-api/revisions/52e77ea7d731?raw)