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.
Before reading this guide it would be helpful to have a clear understanding of users, account groups and accounts in our platform.
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:
||The order has been placed and the corresponding checks are performed, orders with the status
||The order checks have been passed, and the order has been submitted to the trading partner.|
||The order has been executed in whole.|
||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
The order may also change from
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.
||The order was
||The order execution has been settled (typically on T+2). For sell orders, this means that the cash can now be withdrawn.|
||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
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
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:
||Buy or sell an instrument at the market’s current best available 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
STOP orders if the instrument quantity is specified as an integer.
In the future, the Investment API will also support
STOP orders. Currently, only
MARKET orders are possible.
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.
Now you are ready to jump into placing your first order.
Was this page helpful?