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 a list of orders

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

Parameters

Query Parameters

Attribute Type Requirement Description
status string
Optional
Order status to be queried. open, closed or all. Defaults to open.
limit int
Optional
The maximum number of orders in response. Defaults to 50 and max is 500.
after timestamp
Optional
The response will include only ones submitted after this timestamp (exclusive.)
until timestamp
Optional
The response will include only ones submitted until this timestamp (exclusive.)
direction string
Optional
The chronological order of response based on the submission time. asc or desc. Defaults to desc.
nested boolean
Optional
If true, the result will roll up multi-leg orders under the legs field of primary order.
side string
Optional
Filters down to orders that have a matching side field set. See the Order model’s side field for the values you can specify here
symbols string
Optional
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

Get All Orders Recipe

Looking for a way to get all your orders when faced with 500 orders per API call limit? See Get All Orders recipe for a readible code example with Python.

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

Attribute Type Requirement Description
symbol string
Required
symbol, asset ID, or currency pair to identify the asset to trade
qty string<number>
Required
number of coins/tokens to trade.
notional string<number>
Required
dollar amount to trade. Cannot work with qty.
side string
Required
buy or sell
type string
Required
market, limit, stop_limit
time_in_force string
Required
Please see Understand Orders for more info on what values are possible for what kind of orders.
limit_price string<number>
Required
required if type is limit or stop_limit
stop_price string<number>
Required
required if type is stop_limit
client_order_id string (<= 48 characters)
Optional
A unique identifier for the order. Automatically generated if not sent.
order_class string
Optional
simple, bracket, oco or oto. For details of non-simple order classes, please see Bracket Order Overview
take_profit object
Optional
Additional parameters for take-profit leg of advanced orders
stop_loss object
Optional
Additional parameters for stop-loss leg of advanced orders

Response

The new Order object

Errors

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

Get an order

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

Parameters

Path Parameters

Attribute Type Requirement Description
order_id string<uuid>
Optional
Order ID

Response

The requested Order object

Errors

404 Not found
Order is not found.

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

Attribute Type Requirement Description
client_order_id string
Optional
Client Order ID

Response

The requested Order object

Errors

404 Not found
Order is not found.

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

Attribute Type Requirement Description
order_id string<uuid>
Optional
Order ID

Body Parameters

Attribute Type Requirement Description
qty string<int>
Optional
number of shares to trade
time_in_force string
Optional
Please see Understand Orders for more info on what values are possible for what kind of orders.
limit_price string<number>
Optional
required if type is limit or stop_limit
stop_price string<number>
Optional
required if type is stop_limit
client_order_id string (<= 48 characters)
Optional
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.

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.

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

Attribute Type Requirement Description
order_id string<uuid>
Optional
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": "BTC/USD",
  "asset_class": "crypto",
  "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 #

Attribute Type Description
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_type string (Deprecated with just type field below.)
type string<order_type> Valid values: market, limit, stop_limit
side string<side> Valid values: buy, sell
time_in_force string<time_in_force> For crypto, only gtc and ioc. See Orders page.
limit_price string<number> (Nullable) Limit price
status string<order_status> See Orders page