# 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](https://www.tradegate.de/) where the orders are executed and fulfilled on behalf of the users in the Investment API.

## Order types

[Orders](/api/orders/place_order) 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`.

Please note the following:

- The Investment API is designed to support `LIMIT` and `STOP` orders only if the instrument quantity is specified as an integer.
- `LIMIT` and `STOP` orders are offered **only for unit orders** and not for nominal orders.


### Limit and stop order price precision

For limit and stop orders, the executed price may differ slightly from the submitted price.

Trading venues typically impose restrictions on the allowed price precision for limit and stop orders. While our Investment API accepts limit and stop prices as specified, up to 27 decimal places, that precision is not necessarily accepted at the trading venue.

Here's how the final price is determined:

Upvest accepts the entered limit or stop price
We accept the submitted limit or stop price as entered.

**Example:** *An end user enters a limit BUY order with a limit price of 0.123456789 EUR.*

Upvest prepares the order for routing
Trading venues generally accept fewer decimal places than our API allows. Before routing the order, Upvest rounds the price to match the venue's supported precision:

- Limit and stop BUY orders: we round down to the next acceptable price.
- Limit and stop SELL orders: we round up to the next acceptable price.


**Example:** *In our example, the trading venue supports four (4) decimal places for the instrument. The order's price is rounded to 0.1234 EUR.*

The trading venue validates the order
Trading venues are required to follow ESMA's tick size rules, meaning the final price must land on a valid tick increment.

The trading venue may further adjust the price to the nearest valid tick.

**Example:** *The instrument uses 0.005 EUR tick increments. The trading venue rounds down the price to the nearest valid tick. This causes the order's final price to equal 0.1200 EUR.*

## 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 quantity orders, 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 nominal orders, an additional buffer of 10% on the expected instrument quantity is required. In other words, the order is processed if it is estimated to be no more than 90% of the user's current position.
* If the order is placed outside trading hours, as soon as the trading partner is open.


When an account group lacks the sufficient cash balance or instrument quantity to cover an order, that order behaves as follows:

* Regular orders remain in the `New` status until either the account group can cover the cash balance or the order is manually cancelled.
* For orders that are part of block order flow, the order will automatically be cancelled after two (2) attempts to be executed as part of a block.


#### `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.

Please note the following:

- 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.
- In very rare cases, the status `CANCELLED` can also be issued after the status `FILLED`. This happens, for example, if a trading venue has triggered a cancellation.


## 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](/products/omnibus/getting_started/implementing_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](/products/omnibus/guides/orders/block_orders/block_orders_intro).


## 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](/api_errors) 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 may add a +10% buffer to certain orders as described below.

### Buy orders

For buy orders, the +10% cash buffer only applies to **unit buy market** and **unit buy stop orders** to ensure the ability to purchase the total number of units.


| **Order Type** | **Cash buffer (10%)** | **Description** |
|  --- | --- | --- |
| Unit buy market orders | **Yes** | To account for possible price fluctuations, Upvest adds a 10% buffer. This ensures sufficient cash balance to fill the requested quantity. |
| Unit buy stop orders | **Yes** | To ensure sufficient cash balance to purchase securities, Upvest calculates the buffer relative to the submitted stop price. Since the execution price is uncertain after the stop order is triggered, a 10% buffer is applied. |
| Unit buy limit orders | No | Upvest **does not** apply a buffer for unit buy limit orders and will use the limit price instead. |
| Nominal buy market orders | No | Upvest **does not** apply a buffer for nominal buy market orders since the total cash value is already set. |


### Sell orders

For sell orders, the +10% securities buffer only applies to **nominal sell orders** to ensure the ability to purchase enough securities related to the nominal value.


| **Order Type** | **Security buffer (10%)** | **Description** |
|  --- | --- | --- |
| Nominal sell market orders | **Yes** | To account for possible price fluctuations, Upvest adds a 10% buffer. Since the share quantity is estimated from price, the 10% ensures the ability to purchase additional shares. |
| Unit sell market/limit/stop orders | No | Upvest **does not** apply a buffer for unit sell market, limit, and stop orders since the total quantity is already set. |


Orders may be cancelled by Upvest due to an insufficient cash balance or insufficient securities. Once cancelled, the original order can never be executed or submitted to the exchange.

You can safely submit a new order with the same configuration.