Fractional Shares

Under the correspondent authentication, Trading API is extended for fractional shares trading.

Asset API

Asset entity has an extra field named fractionable with type boolean, it is set to true if the asset is marked for fractional trading. Check out more about our Assets API here.

Order API

The POST method (to submit order) has an extra parameter called notional to denote the dollar amount to buy. This parameter is mutually exclusive to the qty parameter. You can also specify the qty parameter with fractional quantity. Note that the fractional shares trading is currently supported only for market day orders and any other type of orders will result in API error. You can submit such fractional share orders in the night to execute at the next market open.

The order entity includes the notional value if the order was submitted with the notional value. In this case, the order entity omits the qty field.

Check out more about our Order API here.

Sample Order Object

 {
    "id": "39c489ad-fcb1-42b3-9f62-e14c11c62157",
    "client_order_id": "a49c3e74-3f74-468e-a31a-f7a15de17128",
    "created_at": "2024-05-20T09:56:41.449735Z",
    "updated_at": "2024-05-20T13:30:00.876162Z",
    "submitted_at": "2024-05-20T13:23:01.24795Z",
    "filled_at": "2024-05-20T13:30:00.865454Z",
    "expired_at": null,
    "canceled_at": null,
    "failed_at": null,
    "replaced_at": null,
    "replaced_by": null,
    "replaces": null,
    "asset_id": "7595a8d2-68a6-46d7-910c-6b1958491f5c",
    "symbol": "A",
    "asset_class": "us_equity",
    "notional": null,
    "qty": "0.1",
    "filled_qty": "0.1",
    "filled_avg_price": "154.03",
    "order_class": "",
    "order_type": "market",
    "type": "market",
    "side": "sell",
    "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",
    "subtag": null,
    "source": "correspondent"
},

Order Properties

Attribute	Type	Description
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 9 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	(Will be deprecated in favor of type field below) Valid values: market, limit, stop, stop_limit, trailing_stop
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 Time in Force 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	Order status. See Order statuses here.
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 commission you want to charge the end user.
commission_type	string	Select how to interpret the value provided in the commission field. Available options: notional(default), qty, bps.
subtag	string/number	An account identifier for Omnibus partners. (Can be null)
source	string	Source of order.

Account Configuration API

Account configuration API adds another configuration key called fractional_trading and defaults to true. If you want to disable fractional trading for a specific account for any reason, you can set this to false.

Commissions

You have the option to charge the commission for each order. You will need to contact Alpaca first to set up the commission structure, but once it’s set up, you can submit customer orders with a commission parameter indicating the dollar amount to charge. The respective field is attached in the order entity in the API response.

To charge commissions, first select desired method with commission_type. Then specify the desired dollar amount or percentage in commission field. Please note: On orders to sell if the commission input will be more than the principal of the transaction then the principal amount of the transaction (net of SEC REG and FINRA TAF fees) will be charged as commission and not the amount specified in the order. On all orders (regardless of commission type), the commission charged will be prorated on each execution if the order has multiple executions. For instance, if 10% of the order is filled on one execution then the commission on that execution will be 10% of the total commission.

notional:
Charge commission on a per order basis. When the commission_type field is omitted from the order request, this is used as the default.
qty:
Charge commission on a per qty/contract basis, pro rated.
bps:
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.

Order Sub-tagging (Omnibus)

If you are an omnibus setup, we ask you to submit a “sub-tag” value in each order. This is for us to understand the order flow better from the trade surveillance requirements. In case you fail to attach proper sub-tags, we may need to reject all of the order flows coming from you as we may not be able to segregate particular malicious activities.

FAQ

What should I do if I receive a timeout message from Alpaca when submitting an order?

The order may have been sent to the market for execution. You should not attempt to resend the order or mark the timed-out order as canceled until confirmed by Alpaca Support or the trading team. Before taking any action on the timed-out order you should check the broker dashboard and contact Alpaca support.
Please contact our Support Team at [email protected] to verify if the order was successfully submitted and routed to the market.