CLclear-street
Orders

Preview Orders

Changed on

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).

post/v1/accounts/{account_id}/orders/preview

Request

  • Base URL
    https://api.clearstreet.com
  • Auth
    HTTP bearer

Path parameters

account_idinteger required

Account identifier

Request body

expires_atstring date-time nullable

The timestamp when the order should expire (UTC). Required when time_in_force is GOOD_TILL_DATE.

extended_hoursboolean nullable

Allow trading outside regular trading hours. Some brokers disallow options outside RTH.

idstring nullable

Optional client-provided unique ID (idempotency). Required to be unique per account.

instrument_idstring

Instrument identifier: either an instrument UUID or a symbol (symbol for equities, OSI for options). Non-UUID inputs are resolved server-side.

limit_offsetstring nullable

Limit offset for trailing stop-limit orders (signed)

limit_pricestring 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.

quantitystring 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_pricestring nullable

Stop price (required for STOP and STOP_LIMIT orders)

symbolstring 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_offsetstring nullable

Trailing offset amount (required for trailing orders)

trailing_offset_type'PRICE' | 'BPS'

Trailing offset type for trailing stop orders.

Example request

[
  {
    "order_type": "MARKET",
    "quantity": "1",
    "side": "BUY",
    "symbol": "TSLA",
    "time_in_force": "DAY"
  }
]

Response

Batch evaluated: one result per order, in request order, each carrying either a preview or that order's error

Example response

{
  "error": {
    "code": 400,
    "message": "Order quantity must be greater than zero"
  },
  "metadata": {
    "page_number": 1,
    "total_items": 42,
    "total_pages": 5
  },
  "data": [
    {
      "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": "190000.00",
          "before": "200000.00",
          "change": "-10000.00"
        },
        "errors": [
          {
            "description": "Insufficient buying power",
            "metadata": {
              "available": "5000",
              "required_total": "10000"
            },
            "type": "BUYING_POWER"
          }
        ],
        "margin_details": {
          "initial_margin_excess": {
            "after": "190000.00",
            "before": "200000.00",
            "change": "-10000.00"
          },
          "initial_margin_requirement": {
            "after": "190000.00",
            "before": "200000.00",
            "change": "-10000.00"
          },
          "maintenance_margin_excess": {
            "after": "190000.00",
            "before": "200000.00",
            "change": "-10000.00"
          },
          "maintenance_margin_requirement": {
            "after": "190000.00",
            "before": "200000.00",
            "change": "-10000.00"
          },
          "overnight_margin_excess": {
            "after": "190000.00",
            "before": "200000.00",
            "change": "-10000.00"
          },
          "overnight_margin_requirement": {
            "after": "190000.00",
            "before": "200000.00",
            "change": "-10000.00"
          }
        },
        "positions": [
          {
            "instrument_id": "a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8",
            "quantity": {
              "after": "190000.00",
              "before": "200000.00",
              "change": "-10000.00"
            },
            "symbol": "AAPL"
          }
        ]
      },
      "id": "my-ref-id-20251001-002"
    }
  ]
}

Changes