To place an order, an Account must first be set up and approved to trade. If you are using the [Account Management](🔗) product, the Account can be owned by any customer. Otherwise, the Account should be your firm’s trading Account set up by DriveWealth.
Generally, Accounts need funds to buy assets. Refer to [Getting balances and positions](🔗) to verify how much cash can be spent in an Order, or refer to [Depositing](🔗) to learn how to get funds into an account.
Immediately before placing an Order, you probably want to show a customer information about the asset and its current price. Refer to [Displaying prices and information](🔗) if that’s the case.
When you’re ready to create an Order, provide the instructions specified by the customer:
You’ll receive an Order ID and human-readable Order number as a response.
## Receiving updates to the Order
You’ll notice the Order creation does not return any details about the processing of the Order. This processing takes time, even while the market is open. To check if an Order has been completed or updated:
This order has been completed, and the customer has purchased 10 shares at a price of $155.00 per share.
## General Order workflow
There are 3 statuses that DriveWealth considers immutable:
When an order is submitted it will be returned with a status of `
NEW`. From here, the status can be updated to any of the following: `
PARTIAL_FILL` will **only** transition to `
FILLED` or `
On fractional orders that are \< 1 share you should not expect to receive a `
PARTIAL_FILL` status. For orders that are fractional but > 1 shares (eg. 5.12580012) you will receive a `
PARTIAL_FILL` status for the whole share execution, and upon fractional share execution the status will be updated to `
For partially filled orders that wind up being canceled, it's possible to determine the executed amount prior to the order cancellation using the `
cumulativeQuantity` in the response. The cumulative quantity is the total amount that has been filled, where the `
quantity` of an order is the amount that was requested.
Orders for Crypto and Mutual Funds will never be partially filled.
In some cases, such as the [Retrieve all Orders by Account](🔗) endpoint, you will receive a number for the orderStatus field. Refer to the table below for the number status pairs.
|0||New||A status of NEW will persist until DriveWealth OMS receives the order. This should happen within milliseconds.|
|1||Partially filled||An order that is partially filled.|
|2||Filled||The order has been filled.|
|4||Canceled||The order was canceled.|
|6||Pending Canceled||An attempt to cancel an order but the order has already been sent to the street for execution. DriveWealth can not guarantee cancellation at this point. However, most Pending Canceled orders will cancel.|
|8||Rejected||Order is rejected by DriveWealth systems. For example, there is not enough buying power in a user's account. Rejected orders do not reach DriveWealth's OMS.|
## Manually canceling an Order
Once an Order is created, it can be canceled manually by the customer. This applies to all types of Orders, like a limit Order to buy at a certain price or an Order to purchase stock overnight.
However, in some cases—like a market order for an equity placed during the day—there may not be any reasonable time for a customer to cancel an Order once it’s placed. For this reason, Order cancellations are by request, and may be unsuccessful.
Placing a request to cancel requires an edit to the Order:
A response does not indicate that the cancellation has been successful, only that the request was received. If the cancellation goes through the Order will update and Events will be received:
## Choosing an Order type
Most assets support multiple types of orders depending on the desired style of execution. The different types of orders are explained below.
Market orders are submitted immediately to execution venues (assuming the security is actively trading) and carry the highest priority. Provided there is sufficient liquidity to fill the order, customers can expect very fast execution, but without any guarantee of price.
The bid or ask the customer sees when placing the trade is an indicative price only, and due to the fast-moving nature of the market, the actual executed price may differ.
Unlike market orders, limit orders have a guarantee of price if filled. To achieve this, an order for a quantity and specified price is sent to an exchange or market maker to be later paired with a buyer or seller also willing to transact at that price. There is no guarantee that the order will be executed—for example: if a customer wants to purchase stock at $100/share, they may not ever receive a fill if the security continues to trade around $120/share.
Buy orders are created with a price below the current ask, and sell orders are created with a price above the current bid. It is possible for the customer to receive a price better than requested. Limit orders can also be set to expire up to 90 days from the date of creation.
Because limit orders need to rest in an order book at a market maker, **limit orders accept whole-share quantities only**.
### Stop & Market if Touched
Stop Orders and market-if-touched orders have very similar functions: they both create market orders when a condition has been reached.
Like limit orders, these Order types require both a quantity (or dollar amount) and a price. Unlike limit orders, this price is not a guarantee. Instead, it is a triggering price which, upon the security trading at, dispatches a market order to buy or sell the requested amount.
Trigger prices should be set according to the following:
Buy stop: If lastTrade >= trigger price
Buy market-if-touched: If ask >= trigger price
Sell stop: If lastTrade \<= trigger price
Sell market-if-touched: If bid \<= trigger price
Market-if-touched orders share the same side of the current price as limit orders. Because of this, they may be considered an alternative to limit orders when fractional orders are desired (keeping in mind the lack of guaranteed price).
To provide a simplified approach to choosing an appropriate order type, consider a workflow that guides the customer similar to the below:
Buy now — (market order)
Buy if price goes up — (stop order)
Buy if price goes down — (market-if-touched order)
## Queuing orders for later
Some assets, like equities, trade only during certain hours. By default, orders placed outside of these hours are queued for execution during the next trading window.
DriveWealth will accept equities orders that are placed after market close, and will hold them overnight to release on market open the following business day.
If you specifically do not want an Order to be queued for the next open, use the `
preventQueuing` parameter when [creating the order](🔗). By sending the order request with this parameter set to true, the order will be rejected if received after 4:00pm ET. This may be helpful if you think the customer is expecting an immediate execution.
To help determine whether an order will be executed immediately or queued for the next market session, there is an `
orderExpires` attribute in the Order status response. For example, an order submitted after hours will have an `
orderExpires` set to 4:00pm ET of the following market session.
Market orders for equities that are submitted overnight are sent to DriveWealth's executing brokers at 9:05am ET and will generally be part of the opening auction. Orders cannot be canceled after these times for the following exchanges:
NASDAQ-listed equities — 9:28am ET
NYSE ARCA-listed equities — 9:29am ET
NYSE American-listed equities — 9:29am ET
BATS Names-listed equities — 9:28am ET
IEX Names-listed equities — 9:28am ET
NYSE Names-listed equities — Open Time
Orders that are submitted after 9:28am ET will not be part of the opening auction.
## Trading after hours
Although equities trade primarily between 9:30 and 4:00pm ET, DriveWealth supports trading these assets in the extended sessions as well: the **Pre-Market Session** (4:00am ET to 9:30am ET) and the **Post-Market Session** (4:00pm ET to 8:00pm ET).
Extended hours trading carries a unique risk profile due to differences in liquidity and pricing. Consider these risks before enabling access to this feature.
You must designate a trade to be eligible for these sessions, but do not need to pick which one:
timeInForce` attribute above enables the Order for extended session execution. All extended hours trades must be submitted as limit Orders.
## Security halts
Sometimes, specific securities are halted from trading by an exchange or by regulators. DriveWealth processes security halts differently for fractional and whole share orders.
**Whole Share** orders that are submitted during a security halt are left in a `
PENDING` state, and will be processed once the halt has been lifted.
**Fractional Share** orders, e.g. 0.555555 shares, that are submitted during a security halt are immediately `
When a security halt does occur, partners are provided an [instrument updated](🔗) event that would be structured as the following: