Orders

The Orders API allows a user to monitor, place and cancel their orders with Alpaca. Each order has a unique identifier provided by the client. This client-side unique order ID will be automatically generated by the system if not provided by the client, and will be returned as part of the order object along with the rest of the fields described below. Once an order is placed, it can be queried using the client-side order ID to check the status. Updates on open orders at Alpaca will also be sent over the streaming interface, which is the recommended method of maintaining order state.

For further details on order functionality, please see the Trading On Alpaca - Orders page.

Please note that body parameters should be passed using a JSON encoded body.

[GET] Get a list of orders

GET/v2/orders
Retrieves a list of orders for the account, filtered by the supplied query parameters.

Parameters

Query Parameters

status
string
Order status to be queried. open, closed or all. Defaults to open.
limit
int
The maximum number of orders in response. Defaults to 50 and max is 500.
after
timestamp
The response will include only ones submitted after this timestamp (exclusive.)
until
timestamp
The response will include only ones submitted until this timestamp (exclusive.)
direction
string
The chronological order of response based on the submission time. asc or desc. Defaults to desc.
nested
boolean
If true, the result will roll up multi-leg orders under the legs field of primary order.
symbols
string
A comma-separated list of symbols to filter by (ex. “AAPL,TSLA,MSFT”). A currency pair is required for crypto orders (ex. “BTCUSD,BCHUSD,LTCUSD,ETCUSD”).

Response

An array of Order object

[POST] Request a new order

POST/v2/orders
Places a new order for the given account. An order request may be rejected if the account is not authorized for trading, or if the tradable balance is insufficient to fill the order.

Parameters

Body Parameters

symbol
stringRequired
symbol, asset ID, or currency pair to identify the asset to trade
qty
string<number>Required
number of shares to trade. Can be fractionable for only market and day order types.
notional
string<number>Required
dollar amount to trade. Cannot work with qty. Can only work for market order types and day for time in force.
side
stringRequired
buy or sell
type
stringRequired
market, limit, stop, stop_limit, or trailing_stop
time_in_force
stringRequired
day, gtc, opg, cls, ioc, fok. Please see Understand Orders for more info.
limit_price
string<number>Required
required if type is limit or stop_limit
stop_price
string<number>Required
required if type is stop or stop_limit
trail_price
string<number>Required
this or trail_percent is required if type is trailing_stop
trail_percent
string<number>Required
this or trail_price is required if type is trailing_stop
extended_hours
boolean
(default) false. If true, order will be eligible to execute in premarket/afterhours. Only works with type limit and time_in_force day.
client_order_id
string (<= 48 characters)
A unique identifier for the order. Automatically generated if not sent.
order_class
string
simple, bracket, oco or oto. For details of non-simple order classes, please see Bracket Order Overview
take_profit
object
Additional parameters for take-profit leg of advanced orders
limit_price
string<number>Required
required for bracket orders
stop_loss
object
Additional parameters for stop-loss leg of advanced orders
stop_price
string<number>Required
required for bracket orders
limit_price
string<number>
the stop-loss order becomes a stop-limit order if specified

Response

The new Order object

Errors

403 Forbidden
Buying power or shares is not sufficient.
422 Unprocessable
Input parameters are not recognized.

[GET] Get an order

GET/v2/orders/{order_id}
Retrieves a single order for the given order_id.

Parameters

Path Parameters

order_id
string<uuid>
Order ID

Query Parameters

nested
boolean
If true, the result will roll up multi-leg orders under the legs field of primary order.

Response

The requested Order object

Errors

404 Not found
Order is not found.

[GET] Get an order by client order id

GET/v2/orders:by_client_order_id
Retrieves a single order for the given client_order_id.

Parameters

Query Parameters

client_order_id
string
Client Order ID

Response

The requested Order object

Errors

404 Not found
Order is not found.

[PATCH] Replace an order

PATCH/v2/orders/{order_id}

Replaces a single order with updated parameters. Each parameter overrides the corresponding attribute of the existing order. The other attributes remain the same as the existing order.

A success return code from a replaced order does NOT guarantee the existing open order has been replaced. If the existing open order is filled before the replacing (new) order reaches the execution venue, the replacing (new) order is rejected, and these events are sent in the trade_updates stream channel. Read more about the trade stream updates here.

While an order is being replaced, buying power is reduced by the larger of the two orders that have been placed (the old order being replaced, and the newly placed order to replace it). If you are replacing a buy entry order with a higher limit price than the original order, the buying power is calculated based on the newly placed order. If you are replacing it with a lower limit price, the buying power is calculated based on the old order.

Parameters

Path Parameters

order_id
string<uuid>
Order ID

Body Parameters

qty
string<int>
number of shares to trade
time_in_force
string
day, gtc, opg, cls, ioc, fok. Please see Understand Orders for more info.
limit_price
string<number>
required if type is limit or stop_limit
stop_price
string<number>
required if type is stop or stop_limit
trail
string<number>
the new value of the trail_price or trail_percent value (works only for type="trailing_stop”)
client_order_id
string (<= 48 characters)
A unique identifier for the order. Automatically generated if not sent.

Response

The new Order object with the new order ID.

Errors

403 Forbidden
Buying power or shares is not sufficient.
422 Unprocessable
Input parameters are not recognized.

[DELETE] Cancel all orders

DELETE/v2/orders
Attempts to cancel all open orders. A response will be provided for each order that is attempted to be cancelled. If an order is no longer cancelable, the server will respond with status 500 and reject the request.

Response

HTTP 207 Multi-Status with body; an array of objects that include the order id and http status code for each status request.

Errors

500
Failed to cancel order.

[DELETE] Cancel an order

DELETE/v2/orders/{order_id}
Attempts to cancel an open order. If the order is no longer cancelable (example: status="filled"), the server will respond with status 422, and reject the request. Upon acceptance of the cancel request, it returns status 204.

Parameters

Path Parameters

order_id
string<uuid>
Order ID

Response

Errors

404 Not found
Order is not found.
422 Unprocessable
The order status is not cancelable.

Order Entity

Example

{
  "id": "61e69015-8549-4bfd-b9c3-01e75843f47d",
  "client_order_id": "eb9e2aaa-f71a-4f51-b5b4-52a6c565dad4",
  "created_at": "2021-03-16T18:38:01.942282Z",
  "updated_at": "2021-03-16T18:38:01.942282Z",
  "submitted_at": "2021-03-16T18:38:01.937734Z",
  "filled_at": null,
  "expired_at": null,
  "canceled_at": null,
  "failed_at": null,
  "replaced_at": null,
  "replaced_by": null,
  "replaces": null,
  "asset_id": "b0b6dd9d-8b9b-48a9-ba46-b9d54906e415",
  "symbol": "AAPL",
  "asset_class": "us_equity",
  "notional": "500",
  "qty": null,
  "filled_qty": "0",
  "filled_avg_price": null,
  "order_class": "",
  "order_type": "market",
  "type": "market",
  "side": "buy",
  "time_in_force": "day",
  "limit_price": null,
  "stop_price": null,
  "status": "accepted",
  "extended_hours": false,
  "legs": null,
  "trail_percent": null,
  "trail_price": null,
  "hwm": null
}

Properties

id
string<uuid>
Order ID
client_order_id
string
Client unique order ID
created_at
string<timestamp>
updated_at
string<timestamp> (Nullable)
submitted_at
string<timestamp> (Nullable)
filled_at
string<timestamp> (Nullable)
expired_at
string<timestamp> (Nullable)
canceled_at
string<timestamp> (Nullable)
failed_at
string<timestamp> (Nullable)
replaced_at
string<timestamp> (Nullable)
replaced_by
string<uuid> (Nullable)
The order ID that this order was replaced by
replaces
string<uuid> (Nullable)
The order ID that this order replaces
asset_id
string<uuid>
Asset ID
symbol
string
Asset symbol
asset_class
string
Asset class
notional
string<number>
Ordered notional amount. If entered, qty will be null. Can take up to 9 decimal points.
qty
string<number>
Ordered quantity. If entered, notional will be null. Can take up to 9 decimal points.
filled_qty
string<number>
Filled quantity
filled_avg_price
string<number> (Nullable)
Filled average price
order_class
string
simple, bracket, oco or oto. For details of non-simple order classes, please see Bracket Order Overview
order_type
string
(Deprecated with just type field below.)
type
string<order_type>
Valid values: market, limit, stop, stop_limit, trailing_stop
side
string<side>
Valid values: buy, sell
time_in_force
string<time_in_force>
See Orders page
limit_price
string<number> (Nullable)
Limit price
stop_price
string<number> (Nullable)
Stop price
status
string<order_status>
See Orders page
extended_hours
boolean
If true, eligible for execution outside regular trading hours.
legs
array<Order>
When querying non-simple order_class orders in a nested style, an array of Order entities associated with this order. Otherwise, null.
trail_percent
string<number>
The percent value away from the high water mark for trailing stop orders.
trail_price
string<number>
The dollar value away from the high water mark for trailing stop orders.
hwm
string<number>
The highest (lowest) market price seen since the trailing stop order was submitted.