Before reading this guide it would be helpful to have a clear understanding of users, account groups and accounts in our platform.
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 (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
LIMITandSTOPorders only if the instrument quantity is specified as an integer. LIMITandSTOPorders are offered only for unit orders and not for nominal orders.
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.
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. |
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
Newstatus 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.
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
PROCESSINGtoCANCELLED. This order will not be re-issued by Upvest and can be safely resubmitted by you. - In very rare cases, the status
CANCELLEDcan also be issued after the statusFILLED. This happens, for example, if a trading venue has triggered a cancellation.
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.
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.
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.
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.
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.
Upvest may add a +10% buffer to certain orders as described below.
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. |
In this example, an end user has €5,000 in cash and submits a unit buy market order. The instrument is currently trading at €100, and Upvest estimates the order's cost from the current price.
The end user submits a unit buy market order for 40 shares. The estimated cost is €4,000 (40 × €100), which is within 90% of the end user's €5,000 cash balance. The order moves to PROCESSING.
The end user submits a unit buy market order for 48 shares. The estimated cost is €4,800, which exceeds 90% of the cash balance. The order remains in NEW until the end user tops up their cash balance, the order is cancelled, or, for block orders, the second execution attempt fails.
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 | Share quantity is estimated from price, so Upvest reserves a 10% buffer to cover price fluctuations. The order is only processed if the estimated quantity is no more than 90% of the end user's available position. |
| 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.
In this example, an end user holds 100 shares of an instrument currently trading at €50. They submit a nominal sell order, and Upvest estimates the share quantity from the current price and processes the order.
The end user submits a nominal sell order for €4,000. The estimated quantity is 80 shares (€4,000 ÷ €50), which is within 90% of the end user's 100-share position. The order moves to PROCESSING.
The end user submits a nominal sell for €4,750. The estimated quantity is 95 shares, which exceeds 90% of the position. The order remains in NEW until the end user's position increases, the order is cancelled, or, for block orders, the second execution attempt fails.