Operating Model:
Operating Model:

Orders

This guide provides you with all 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 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.
COMING SOON

Once the order executions are settled (typically on T+2) you will also receive an order execution SETTLED webhook.

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

Implementing orders

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.

Order state transitions

NEW to PROCESSING

In order for an order to change from NEW to PROCESSING status, the following conditions must be met:

  • 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.

PROCESSING to FILLED

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

  • The order is placed outside trading hours and will be executed as soon as the trading partner is open.
  • 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 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.

COMING SOON

In the future, the Investment API will also support LIMIT and STOP orders. Currently, only MARKET orders are possible.

Cancelling an order

MARKET orders can only be cancelled whilst in the NEW status. To cancel an existing order, call the cancellation endpoint with the appropriate order ID, using DELETE /orders/{order_id}.

LIMIT orders can be cancelled up to the PROCESSING state and STOP orders can be cancelled before the stop-price has been reached in the PROCESSING state.

Handling errors

The Investment API will only return synchronous errors on order creation in two scenarios: either the request is malformed or the values provided are valid but unprocessable. The later case will occur if the account ID does not exist in the system yet.

  • HTTP 400 Bad request
  • HTTP 422 Unprocessable entity

Other errors that can happen in order processing are asynchronous and will be represented by a state change to CANCELLED and will have a descriptive error message.

COMING SOON

Detailed enumeration of error messages will follow soon in the next iteration of the guide.

Next steps

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

Was this page helpful?