## Preview Orders

`OrderPreviewOrdersResponse v1().orders().previewOrders(OrderPreviewOrdersParamsparams, RequestOptionsrequestOptions = RequestOptions.none())`

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

### Parameters

- `OrderPreviewOrdersParams params`

  - `Optional<Long> accountId`

  - `List<NewOrderRequest> preview`

    - `RequestOrderType orderType`

      Type of order

      - `MARKET("MARKET")`

      - `LIMIT("LIMIT")`

      - `STOP("STOP")`

      - `STOP_LIMIT("STOP_LIMIT")`

      - `TRAILING_STOP("TRAILING_STOP")`

      - `TRAILING_STOP_LIMIT("TRAILING_STOP_LIMIT")`

    - `String quantity`

      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("BUY")`

      - `SELL("SELL")`

    - `RequestTimeInForce timeInForce`

      Time in force

      - `DAY("DAY")`

      - `GOOD_TILL_CANCEL("GOOD_TILL_CANCEL")`

      - `IMMEDIATE_OR_CANCEL("IMMEDIATE_OR_CANCEL")`

      - `FILL_OR_KILL("FILL_OR_KILL")`

      - `GOOD_TILL_DATE("GOOD_TILL_DATE")`

      - `AT_OPEN("AT_OPEN")`

      - `AT_CLOSE("AT_CLOSE")`

    - `Optional<String> id`

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

    - `Optional<LocalDateTime> expiresAt`

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

    - `Optional<Boolean> extendedHours`

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

    - `Optional<String> instrumentId`

      Instrument ID (UUID) or symbol (equity ticker or OSI option symbol). Either `symbol` or `instrument_id` must be provided.

    - `Optional<String> limitOffset`

      Limit offset for trailing stop-limit orders (signed)

    - `Optional<String> limitPrice`

      Limit price (required for LIMIT and STOP_LIMIT orders)

    - `Optional<RequestPositionEffect> positionIntent`

      Optional open/close intent for this order. When omitted, the platform
      determines the position effect.

      - `OPEN("OPEN")`

      - `CLOSE("CLOSE")`

    - `Optional<String> stopPrice`

      Stop price (required for STOP and STOP_LIMIT orders)

    - `Optional<OrderStrategy> strategy`

      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`

        - `InnerType type`

          Execution strategy type.

          - `SOR("SOR")`

      - `UnionMember1`

        - `Type type`

          Execution strategy type.

          - `VWAP("VWAP")`

        - `Optional<LocalDateTime> endAt`

          UTC timestamp (RFC 3339) by which to finish working the order. Defaults to market close.

        - `Optional<LocalDateTime> startAt`

          UTC timestamp (RFC 3339) at which to begin working the order. Defaults to the time the order is received.

      - `UnionMember2`

        - `Type type`

          Execution strategy type.

          - `TWAP("TWAP")`

        - `Optional<LocalDateTime> endAt`

          UTC timestamp (RFC 3339) by which to finish working the order. Defaults to market close.

        - `Optional<LocalDateTime> startAt`

          UTC timestamp (RFC 3339) at which to begin working the order. Defaults to the time the order is received.

      - `UnionMember3`

        - `String destination`

          Venue code the order is routed to.

        - `Type type`

          Execution strategy type.

          - `DMA("DMA")`

    - `Optional<String> symbol`

      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.

    - `Optional<String> trailingOffset`

      Trailing offset amount (required for trailing orders)

    - `Optional<TrailingOffsetType> trailingOffsetType`

      Trailing offset type (PRICE or PERCENT_BPS)

      - `PRICE("PRICE")`

      - `BPS("BPS")`

### Returns

- `class OrderPreviewOrdersResponse:`

  - `List<OrderPreviewEntry> data`

    - `UnionMember0`

      - `OrderPreview preview`

        The projected impact of the order.

        - `long accountId`

          The account the order was previewed for.

        - `OrderPreviewAmount amount`

          Monetary size of the previewed order.

          - `String grossAmount`

            Total cash impact of the order before estimated fees and commissions.

          - `String netAmount`

            Total cash impact of the order after estimated fees and commissions.

        - `OrderPreviewDelta buyingPower`

          Buying power before and after the order.

          - `String after`

            The value with the previewed order also fully filled.

          - `String before`

            The value before the order, as the risk engine evaluates it: the
            account's open orders are projected as filled.

          - `String change`

            The previewed order's isolated impact: `after - before`.

        - `String currency`

          Currency for all monetary values.

        - `OrderPreviewDelta equity`

          Account equity before and after the order.

        - `List<OrderPreviewError> errors`

          Risk-check errors that would prevent the order from being
          accepted. Empty when the order would pass every pre-trade risk check.

          - `String description`

            Human-readable description of the error.

          - `Metadata metadata`

            Structured details for the error (stringified values), e.g.
            required and available amounts, and `leg_index`/`leg_symbol` for
            multileg leg errors.

          - `String type`

            Stable error code.

        - `OrderPreviewMarginDetails marginDetails`

          Margin requirements and excess before and after the order.

          - `OrderPreviewDelta initialMarginExcess`

            Initial margin excess.

          - `OrderPreviewDelta initialMarginRequirement`

            Initial margin requirement.

          - `OrderPreviewDelta maintenanceMarginExcess`

            Maintenance margin excess.

          - `OrderPreviewDelta maintenanceMarginRequirement`

            Maintenance margin requirement.

          - `OrderPreviewDelta overnightMarginExcess`

            Overnight margin excess.

          - `OrderPreviewDelta overnightMarginRequirement`

            Overnight margin requirement.

        - `List<OrderPreviewPosition> positions`

          Positions in the traded instruments before and after the order.

          - `String instrumentId`

            The instrument's identifier.

          - `OrderPreviewDelta quantity`

            Net position quantity before and after the order.

          - `String symbol`

            The instrument's symbol.

      - `Optional<String> id`

        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.

    - `UnionMember1`

      - `ApiError error`

        Why this order's preview failed.

        - `long code`

          The error code is used to identify the nature of the error. It corresponds
          to an HTTP status code.

        - `String message`

          A human-readable message providing more details about the error.

        - `Optional<List<Detail>> details`

          Additional error details, if any. This can include structured information
          such as field violations or error metadata.

      - `Optional<String> id`

        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

```java
package com.clearstreet.api.example;

import com.clearstreet.api.client.ClearStreetClient;
import com.clearstreet.api.client.okhttp.ClearStreetOkHttpClient;
import com.clearstreet.api.models.v1.orders.NewOrderRequest;
import com.clearstreet.api.models.v1.orders.OrderPreviewOrdersParams;
import com.clearstreet.api.models.v1.orders.OrderPreviewOrdersResponse;
import com.clearstreet.api.models.v1.orders.RequestOrderType;
import com.clearstreet.api.models.v1.orders.RequestTimeInForce;
import com.clearstreet.api.models.v1.orders.Side;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        ClearStreetClient client = ClearStreetOkHttpClient.builder()
            .fromEnv()
            .apiKey("My API Key")
            .build();

        OrderPreviewOrdersParams params = OrderPreviewOrdersParams.builder()
            .accountId(0L)
            .addPreview(NewOrderRequest.builder()
                .orderType(RequestOrderType.LIMIT)
                .quantity("100")
                .side(Side.BUY)
                .timeInForce(RequestTimeInForce.DAY)
                .build())
            .addPreview(NewOrderRequest.builder()
                .orderType(RequestOrderType.LIMIT)
                .quantity("10")
                .side(Side.BUY)
                .timeInForce(RequestTimeInForce.DAY)
                .build())
            .build();
        OrderPreviewOrdersResponse response = client.v1().orders().previewOrders(params);
    }
}
```

#### 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"
  }
}
```