Orders #

The Orders API allows you to monitor, place and cancel your end user order requests. Each order has a unique identifier (client_order_id) that could be provided by you. 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_order_id or order_id to check the status. Updates on open orders at Alpaca will also be sent over the streaming interface found here, which is the recommended method of maintaining order state.

The Order Object #

Sample Order Object # 

{
  "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,
  "commission": "1.25",
  "commission_bps": "100"
}

Attributes #

Attribute Type Notes
id string/UUID Order ID generated by Alpaca
client_order_id string/UUID Client unique order ID
created_at string/timestamp Time when order was entered
updated_at string/timestamp Time of most recent change to the order
submitted_at string/timestamp Time the order was submitted for execution or, if not yet submitted the created_at time. Because orders are submitted for execution asynchronous to database updates, at times this may be before the created_at time.
filled_at string/timestamp Time the order was filled. Can be null if not filled
expired_at string/timestamp Can be null
cancelled_at string/timestamp Can be null
failed_at string/timestamp Can be null
replaced_at string/timestamp Can be null
replaced_by string/UUID The order ID that this order was replaced by. (Can be null)
replaces string/UUID The order ID that this order replaces. (Can be null)
asset_id string/UUID The asset ID
symbol string The asset symbol
asset_class string The asset class
notional string/number Ordered notional amount. If entered, qty will be null. Can take up to 2 decimal points.
qty string/number Ordered quantity. If entered, notional will be null. Can take up to 2 decimal points.
filled_qty string/number Filled quantity
filled_avg_price string/number Filled average price. Can be 0 until order is processed in case order is passed outside of market hours
order_class string Valid values: simple, bracket, oco or oto
order_type string/number (Deprecated with just type field below.)
type string Valid values: market, limit, stop, stop_limit, trailing_stop
side string Valid values: buy and sell
time_in_force string Please see the relevant section in Understand Orders for more info on what values are possible for what kind of orders.
limit_price string/number Limit price
stop_price string/number Stop price
status string Enum.OrderStatus
extended_hours boolean If true, eligible for execution outside regular trading hours.
legs array 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.
commission string/number The dollar value commission you want to charge the end user.
commission_bps string/number The percent commission you want to charge the end user on the order (expressed in bps). Alpaca will convert the order to a notional amount for purposes of calculating commission
swap_rate string/number Swap rate is the exchange rate (without mark-up) used to convert the price into local currency or crypto asset
swap_fee_bps string/number Fee in basis points on top swap rate charged by the correspondent on every order
usd object Nested object to encompass the USD equivalent fields for the local currency fields

Enums #

Order Status #

Status Description
new The order has been received by Alpaca, and routed to exchanges for execution. This is the usual initial state of an order.
accepted
held For multi-leg orders, the secondary orders (stop loss, take profit) will enter this state while waiting to be triggered.
partially_filled The order has been partially filled.
filled The order has been filled, and no further updates will occur for the order.
done_for_day The order is done executing for the day, and will not receive further updates until the next trading day
canceled The order has been canceled, and no further updates will occur for the order. This can be either due to a cancel request by the user, or the order has been canceled by the exchanges due to its time-in-force.
expired The order has expired, and no further updates will occur for the order.
replaced The order was replaced by another order, or was updated due to a market event such as corporate action.
pending_cancel The order is waiting to be canceled.
pending_replace The order is waiting to be replaced by another order. The order will reject cancel request while in this state.

Less common states are described below. Note that these states only occur on very rare occasions, and most orders will likely never reach these states:

Status Description
accepted The order has been received by Alpaca, but hasn’t yet been routed to the execution venue. This could be seen often outside of trading session hours.
pending_new The order has been received by Alpaca, and routed to the exchanges, but has not yet been accepted for execution. This state only occurs on rare occasions.
accepted_for_bidding The order has been received by exchanges, and is evaluated for pricing. This state only occurs on rare occasions.
stopped The order has been stopped, and a trade is guaranteed for the order, usually at a stated price or better, but has not yet occurred. This state only occurs on rare occasions.
rejected The order has been rejected, and no further updates will occur for the order. This state occurs on rare occasions and may occur based on various conditions decided by the exchanges.
suspended The order has been suspended, and is not eligible for trading. This state only occurs on rare occasions. No further updates will occur for the order.
calculated The order has been completed for the day (either filled or done_for_day), but remaining settlement calculations are still pending. This state only occurs on rare occasions.

An order may be canceled through the API up until the point it reaches a state of either filled, canceled, or expired.

Fractional Trading #

All correspondent accounts at Alpaca have fractional trading enabled by default. You can now allow your users to participate in fractional trading in two ways:

  1. Inputting a fractional amount in qty
  2. Inputting a notional amount in the notional field of the POST request body

Passing Commissions #

If you want to collect commissions on trades requested by your users you can simply pass in the POST request body a dollar amount in a string in the commission field, or a percentage of the order (in bps) in the commission_bps field.

{
  "symbol": "AAPL",
  "qty": "4.125",
  "side": "buy",
  "type": "market",
  "time_in_force": "day",
  "commission": "1"
}

Creating an Order #

POST /v1/trading/accounts/{account_id}/orders

Creating an order for your end customer. Each trading request must pass in the account_id in the URL.

Request #

Sample Request # 

{
  "symbol": "ETHUSD",
  "qty": "4.125",
  "side": "buy",
  "type": "market",
  "time_in_force": "gtc"
}

Parameters #

Attribute Type Requirement Notes
symbol string
Required
Symbol or asset ID 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 time_in_force = day.
side string
Required
buy or sell
type string
Required
market, limit, stop, stop_limit, or trailing_stop
time_in_force string
Required
Please see the relevant section in 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 or stop_limit
trail_price string/number
Optional
Required
If type is trailing_stop, trail_price or trail_percent is required
trail_percent string/number
Optional
Required
If type is trailing_stop, trail_price or trail_percent is required
extended_hours string
Optional
Defaults to 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/UUID
Optional
A unique identifier for the order. Automatically generated if not sent. (<= 48 characters)
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
Takes in a string/number value for limit_price
stop_loss object
Optional
Takes in a string/number values for stop_price and limit_price
commission string/numeric
Optional
The commission you want to collect from the user.
commission_bps string/numeric
Optional
The commission you want to collect from the user, expressed in bps on the order.
source string/numeric
Optional
instructions string/numeric
Optional
subtag string/numeric
Optional
swap_fee_bps string/numeric
Optional

Note that when submitting crypto orders, Market, Limit and Stop Limit orders are supported while the supported time_in_force values are gtc, and ioc. We accept fractional orders as well with either notional or qty provided.

Response #

Returns an Order object.

Estimating an Order #

POST /v1/trading/accounts/{account_id}/orders/estimation

Order estimation endpoint will display, based on user’s account balance, the estimated quantity and price they will receive for their notional order.

For LCT - customer’s order will include the Alpaca swap_fee, while correspondent side swap_fee is configurable in the API call. Utilising this API does not result in a real order and after the calculation - the user’s buying power reverts to the previous state.

Responses and Errors are the same as with the Orders API

Please note that the estimation is based on the market condition at the time of submission and a live order will differ. The output should be considered indicative.

Note: This does not support Crypto or non-market orders at this time.

Request #

Sample Request # 

{
  "symbol": "AAPL",
  "side": "buy",
  "type": "market",
  "time_in_force": "day",
  "notional": "40",
  "swap_fee_bps": 45
}

Response # 

{
    "id": "bc215c69-b3c9-44b4-afff-896962ea6fd0",
    "client_order_id": "1eebf13e-0308-40f4-b4a1-0bb0b37bc896",
    "created_at": "2022-08-18T19:21:41.316050251Z",
    "updated_at": "2022-08-18T19:21:41.316050251Z",
    "submitted_at": "2022-08-18T19:21:41.3135829Z",
    "filled_at": "2022-08-18T19:21:41.3135829Z",
    "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": "40",
    "qty": null,
    "filled_qty": "0.0016",
    "filled_avg_price": "23717.854",
    "order_class": "",
    "order_type": "market",
    "type": "market",
    "side": "buy",
    "time_in_force": "day",
    "limit_price": null,
    "stop_price": null,
    "status": "filled",
    "extended_hours": false,
    "legs": null,
    "trail_percent": null,
    "trail_price": null,
    "hwm": null,
    "commission": "0",
    "swap_rate": "135.88",
    "swap_fee_bps": "70",
    "subtag": null,
    "source": null,
    "usd": {
        "notional": "0.2923",
        "filled_avg_price": "174.55"
    }
}

Getting All Orders #

GET /v1/trading/accounts/{account_id}/orders

Retrieves a list of orders for the account, filtered by the supplied query parameters. Endpoint defaults to open orders if no parameters are provided.

Request #

Parameters #

Attribute Type Requirement Notes
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.
symbols string
Optional
A comma-separated list of symbols to filter by (ex. “AAPL,BTCUSD,TSLA).
qty_above string/number
Optional
qty_below string/number
Optional
subtag string
Optional

Response #

An array of Order object

Getting an Order By Order ID #

GET /v1/trading/accounts/{account_id}/orders/{order_id}

Retrieves a single order for the given order_id.

Request #

Parameters #

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

Response #

The requested Order object

Error Codes #

404 - Order is not found

Getting an Order By Client Order ID #

GET /v1/trading/accounts/{account_id}/orders:by_client_order_id

Retrieves a single order for the given client_order_id passed as a query parameter.

Request #

Sample Request #

GET /v1/trading/accounts/7669ddfa-3592-41e7-befa-e3da441c913a/orders:by_client_order_id?client_order_id=28b224a5-eaef-448a-9a8f-3c6a2d02f07f

Parameters #

Attribute Type Notes
client_order_id string QUERY - The client order ID

Response #

An array containing the requested Order object

Error Codes #

404 - Order is not found

Patching an Order #

PATCH /v1/trading/accounts/{account_id}/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 found 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.

Request #

Parameters #

Attribute Type Notes
qty string/int You can only patch full shares for now
time_in_force string/number Please see the relevant section in Understand Orders for more info on what values are possible for what kind of orders.
limit_price string/number Required if type = limit or stop_limit
stop_price string/number Required if type = stop or stop_limit
trail string/number The new value of the trail_price or trail_percent
client_order_id string/UUID

Response #

A new Order object with a new order_id

Error Codes #

403 - Forbidden

Buying power or shares is not sufficient

422 - Unprocessable

Input parameters are not recognized

Deleting All Orders #

DELETE /v1/trading/accounts/{account_id}/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.

Request #

N/A

Response #

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

Sample Response Body # 

[
  {
      "id": "aaeec1f3-4917-4cfd-b89f-bab24495d2ff",
      "status": 200,
      "body": {
          "asset_class": "us_equity",
          "asset_id": "93f58d0b-6c53-432d-b8ce-2bad264dbd94",
          "canceled_at": null,
          "client_order_id": "eb9e2aaa-f71a-4f51-b5b4-52a6c565d115",
          "commission": "1",
          "created_at": "2021-06-01T07:50:08.061602Z",
          "expired_at": null,
          "extended_hours": false,
          "failed_at": null,
          "filled_at": null,
          "filled_avg_price": null,
          "filled_qty": "0",
          "hwm": null,
          "id": "aaeec1f3-4917-4cfd-b89f-bab24495d2ff",
          "legs": null,
          "limit_price": "500",
          "notional": null,
          "order_class": "simple",
          "order_type": "stop_limit",
          "qty": "1",
          "replaced_at": null,
          "replaced_by": null,
          "replaces": null,
          "side": "buy",
          "status": "pending_cancel",
          "stop_price": "600",
          "submitted_at": "2021-06-01T07:50:08.048115Z",
          "symbol": "AAPL",
          "time_in_force": "gtc",
          "trail_percent": null,
          "trail_price": null,
          "type": "stop_limit",
          "updated_at": "2021-06-01T07:50:16.746769274Z"
      }
  },
  {
      "id": "f235da63-19c6-49c5-b179-1680576cf42b",
      "status": 200,
      "body": {
          "asset_class": "us_equity",
          "asset_id": "93f58d0b-6c53-432d-b8ce-2bad264dbd94",
          "canceled_at": null,
          "client_order_id": "eb9e2aaa-f71a-4f51-b5b4-52a6c565d114",
          "commission": "1",
          "created_at": "2021-06-01T07:50:01.164738Z",
          "expired_at": null,
          "extended_hours": false,
          "failed_at": null,
          "filled_at": null,
          "filled_avg_price": null,
          "filled_qty": "0",
          "hwm": null,
          "id": "f235da63-19c6-49c5-b179-1680576cf42b",
          "legs": null,
          "limit_price": "500",
          "notional": null,
          "order_class": "simple",
          "order_type": "stop_limit",
          "qty": "1",
          "replaced_at": null,
          "replaced_by": null,
          "replaces": null,
          "side": "buy",
          "status": "pending_cancel",
          "stop_price": "600",
          "submitted_at": "2021-06-01T07:50:01.154208Z",
          "symbol": "AAPL",
          "time_in_force": "gtc",
          "trail_percent": null,
          "trail_price": null,
          "type": "stop_limit",
          "updated_at": "2021-06-01T07:50:16.757113006Z"
      }
  }
]

Error Codes #

500 - Failed to cancel order.

Deleting an Order By Order ID #

DELETE /v1/trading/accounts/{account_id}/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.

Request #

Parameters #

Attribute Type Notes
order_id string QUERY - The order ID

Response #

204 - Success (No Content)

Error Codes #

404 - Not Found: Order is not found
422 - Unprocessable: The order status is not cancelable

 

Edit Edit this page
© 2023 Alpaca Securities LLC All rights reserved.
© 2023 Alpaca Crypto LLC All rights reserved.
© 2023 AlpacaDB, Inc. All rights reserved.

Securities brokerage services are provided by Alpaca Securities LLC ("Alpaca Securities"), member FINRA/SIPC, a wholly-owned subsidiary of AlpacaDB, Inc. Technology and services are offered by AlpacaDB, Inc.

Cryptocurrency services are made available by Alpaca Crypto LLC ("Alpaca Crypto"), a FinCEN registered money services business (NMLS # 2160858), and a wholly-owned subsidiary of AlpacaDB, Inc. Alpaca Crypto is not a member of SIPC or FINRA. Cryptocurrencies are not stocks and your cryptocurrency investments are not protected by either FDIC or SIPC. Please see the Disclosure Library for more information.

This is not an offer, solicitation of an offer, or advice to buy or sell securities or cryptocurrencies, or open a brokerage account or cryptocurrency account in any jurisdiction where Alpaca Securities or Alpaca Crypto respectively, are not registered or licensed, as applicable.