Orders

This guide provides you with the necessary information to understand order processing in the Investment API and how best to implement orders in your application.

How orders work

An order in our system is a command to buy or sell securities and other assets through the Investment API. We are connected to trading partners, such as Tradegate Exchange, where the orders are executed and fulfilled on behalf of the users in the Investment API.

Orders can be created as nominal or unit orders (commonly referred to as share orders). For nominal orders you need to input the desired cash amount. Our fractions engine handles the conversion of the order amount into shares and placing the order in the background.

INFO

Before reading this guide it would be helpful to have a clear understanding of users, account groups and accounts in our platform.

Order states

An order's full lifecycle is represented through our Investment API as a set of states. The state of an order at any given time provides a clear perspective on the stage of order processing, and possible order actions:

State	Description
`NEW`	The order has been placed and the corresponding checks are performed, orders with the status `NEW` can be cancelled.
`PROCESSING`	The order checks have been passed, and the order has been submitted to the trading partner.
`FILLED`	The order has been executed in whole.
`CANCELLED`	The order was cancelled by you or due to an error at the trading partner.

Order state transitions

NEW to PROCESSING

To change an order from the status NEW to the status PROCESSING, the following conditions must be fulfilled:

The account is ACTIVE, i.e., all user checks for the account holder have been performed and passed.
For buy orders: The account group has sufficient cash balance to purchase the securities. For orders with a specified number of instrument, an additional cash buffer of 10% on the expected market value of the order is required.
For sell orders: The account has sufficient instrument quantity to sell the securities. For orders with a nominal value, an additional buffer of 10% on the expected instrument quantity is required.
If the order is placed outside trading hours, as soon as the trading partner is open.

PROCESSING to FILLED

An order remains in the PROCESSING status if the following conditions are met:

The order is not fully filled by the exchange.

Once the order fulfillment is confirmed by the trading partner, it changes to the FILLED status.

WARNING

The order may also change from PROCESSING to CANCELLED if the trading partner detects an error in the order. This order will not be re-issued by Upvest and can be safely resubmitted by you.

Order execution states

In addition, each order execution associated with an order has its own set of states to provide a more detailed picture of the status of the order processing.

State	Description
`FILLED`	The order was `FILLED` in full or in part by the trading partner, depending on the execution amount. The securities and cash positions were updated accordingly.
`SETTLED`	The order execution has been settled (typically on T+2). For sell orders, this means that the cash can now be withdrawn.
`CANCELLED`	The order execution has been cancelled due to an error at the trading partner, i.e. a mistrade.

Every time a state changes, Upvest emits a webhook event. For more information, see how to subscribe to the webhooks.

Order execution state transitions

FILLED to SETTLED

In order for an order execution to change from the FILLED to SETTLED status, the following condition must be met:

The order execution must have been settled by our custodian bank.

For sell orders, the cash can be withdrawn as soon as the order execution changes to the SETTLED status.

Order types

As mentioned above, orders can be placed by either specifying the cash amount or instrument quantity of the order. The instrument quantity can be specified as a decimal number (up to 10 decimal places). The Investment API is designed to support the following order types:

Type	Description
`MARKET`	Buy or sell an instrument at the market’s current best available price.
`LIMIT`	`MARKET` order with a restriction on the maximum price to be paid or the minimum price to be received.
`STOP`	`MARKET` order once the instrument has traded at or through a specified price.

Unit orders with a fractional instrument quantity and nominal orders can only have an order type of MARKET. The Investment API is designed to support LIMIT and STOP orders if the instrument quantity is specified as an integer.

Execution flows

Upvest supports two execution flows for all incoming orders:

STRAIGHT_THROUGH: All orders with this execution flow are directly executed. This flow is the default.
BLOCK: All orders with this execution flow will be grouped together and executed at the next cut-off time. See Block Orders for further details.

Asynchronous order processing

The order processing flow is asynchronous, which means that upon submission of a new order you will receive a HTTP status 202 Accepted. Further information about the order and order execution can be gathered either through webhooks as mentioned above or by directly fetching the order or order execution details via the API.

Upvest always accept orders regardless of whether:

The user checks are passed.
The account is currently locked for any reason (e.g., compliance reasons).
The user has sufficient funds in their account.
The exchange is open.
The ISIN is open for trading on that day.

Only when all checks have been passed, the order is forwarded to the trading partner. This way, you do not have to wait until all checks are passed synchronously before submitting the order to Upvest.

Next steps

Now you are ready to jump into placing your first order.