Overview

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 or J.P. Morgan where the orders are executed and fulfilled on behalf of the users in the Investment API.

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

Order types

Orders can be created as nominal or unit orders (often referred to as share orders).

Order can be placed by specifying the cash amount or instrument quantity of the order. Our fractions engine handles the conversion of the order amount into shares and placing the order in the background.

The instrument quantities can be specified as a decimal number with up to 10 decimal places.

The Investment API is designed to support the following order types:

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

Nominal orders, and unit orders with a fractional instrument quantity, can only have an order type of MARKET.

The Investment API is designed to support LIMIT and STOP orders only if the instrument quantity is specified as an integer.

Order statuses

An order's full life-cycle is represented through the Upvest Investment API as a set of statuses. The status of an order at any given time provides a clear perspective on the stage of order processing, and possible order actions:

Status	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. NOTE: For orders in `PROCESSING` status, cancellation is a best-effort and it cannot be guaranteed that it can be cancelled before execution.
`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 status transitions

`NEW` to `PROCESSING`

An order changes from the status NEW to the status PROCESSING, when the following conditions are 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 fulfilment is confirmed by the trading partner, it changes to the FILLED status.

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

Order execution statuses

Every order execution associated with an order has its own set of statuses to provide a more detailed picture of the status of the order processing.

Status	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 (duration depends on the asset class, e.g., money market funds or investment funds). 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 status changes, Upvest emits a webhook event. For more information, see how to subscribe to the webhooks.

Order execution status 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 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. Block order are discussed in more detail in our dedicated Block Orders guide.

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 by handling the emitted webhooks or by fetching the details of an order or order execution, via the API.

Webhooks notify you of events in business processes, not the success or failure of the initialisation of those processes.

Please be sure to check the HTTP status of the response to your requests and handle failure cases appropriately.

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.

When can an order be placed?

You can always place an order with our Investment API regardless of whether:

The user checks are passed (know-your-customer, proof-of-residence, suitability check).
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 that day.

However, the order will only be executed when all the previous requisites are met.

Conducting a suitability check means that to offer investment products to your users, you are required to assess their investment experience and knowledge for different instruments.

Additional cash / security buffers

Upvest adds a +10% buffer to nominal sell orders and unit by orders

Order Type	Reason
Nominal sell order	To account for possible price fluctuations, Upvest adds a 10% buffer, i.e. the order is processed if it is estimated to be no more than 90% of the user's current position.
Unit buy orders	To ensure sufficient cash balance to purchase securities, i.e. the order will be processed if it is estimated to be no more than 90% of the user’s cash balance.

Orders may be cancelled by Upvest in the event of insufficient cash balance or insufficient securities. However, it is important to note that if an order is cancelled by Upvest, the order can never be executed or placed again, so you can safely place the order again.