API status

Understanding portfolio orders

A portfolio order in our system is an instruction to buy and/or sell a set of instruments. This set of instruments is defined by a portfolio allocation. A portfolio order consists of many individual orders, each of which is processed as described in this guide.

The granularity of order management provides full transparency in order processing and enables advanced portfolio management use cases such as direct indexing.

Order types

In general, the Investment API supports the following portfolio order types:

TypeNameDescription
BUYNominal portfolio buy orderNominal orders are defined by a cash amount (e.g. 1.000). The amount in a nominal buy order is divided amongst all instruments in an allocation based on their target weights.
SELLNominal portfolio sell orderA portfolio sell order will always result in investments being sold according to the current allocation of the respective account. Nominal sell orders cannot exceed 90% of the Net Asset Value (NAV) of the portfolio investment.
REBALANCINGRebalancing orderA portfolio order of this type is created when a rebalancing is triggered for a particular account. It contains both buy and sell orders which, when executed, will rebalance the user’s portfolio investment with the desired target allocation.

Lifecycle of a portfolio order

Placing a portfolio order follows our standard order approach; its entire lifecycle is represented as a series of states.

The state of a portfolio order at a given point in time provides a clear perspective of the state of order processing and possible order actions:

StateDescription
NEWA portfolio order has been placed, relevant checks are being conducted.
PROCESSINGAll individual orders have been created. The order checks have been passed and the individual orders are being processed.
FILLEDAll individual orders have been successfully executed. The securities and cash positions have been updated accordingly.
SETTLEDA portfolio order switches to this status when all individual orders have also been settled. Learn more about the SETTLED status here.
CANCELLEDRebalancing execution orders can be cancelled for various reasons. All possible cases are listed in the table below.

Cancellation reasons

Cancellation reasonDescription
ACOUNT_IS_EMPTYThe account has no positions.
ACCOUNT_NOT_FOUNDThe portfolio account was not found.
CANCELLED_BY_CLIENTCancellation at the customer's request.
CANCELLED_BY_UPVESTCancelled by Upvest.
CONFIGURATION_IS_MISSINGThe account has no portfolio configuration.
INVALID_ACCOUNT_TYPEA rebalancing on a trading account is not allowed.
PORTFOLIO_IS_BALANCEDThe portfolio is already balanced, rebalancing is not required. (The threshold that defines what ‘balance’ means is configurable and can be set by the customer).
INVALID_ACCOUNT_STATUSThe account is in a state other than ACTIVE and cannot be rebalanced.

State transitions

NEW to PROCESSING

In the NEW state, the portfolio order has been received and relevant checks are being conducted. The portfolio order is divided into its individual order components based on the defined allocation.
Once the first individual order is sent to the exchange, the state of the portfolio order changes to the PROCESSING state.

PROCESSING to FILLED

In the PROCESSING state, all the single orders are executed at the respective trading partners. Once all individual orders have been successfully executed, the portfolio order changes to the FILLED state.

Portfolio order object

To make the entire order flow as transparent as possible, the portfolio order is designed as a nested object of individual orders, where each single order can be queried for detailed information using our standard order engine.

Example portfolio sell order object

{
  "id": "54b8d84f-5bd0-4e43-bf0f-164388cb4c23",
  "created_at": "2021-07-21T14:10:00.00Z",
  "type": "PORTFOLIO_ORDER.NEW",
  "object": {
    "id": "eb5ba93f-5dfe-4bf1-8571-4da0caacc80c",
    "created_at": "2021-07-21T14:10:00.000Z",
    "updated_at": "2021-07-21T14:10:00.000Z",
    "account_id": "debf2026-f2da-4ff0-bb84-92e45babb1e3",
    "allocation_id": "debf2026-f2da-4ff0-bb84-92e45babb1e3",
    "cash_amount": "1000",
    "currency": "EUR",
    "status": "PROCESSING",
    "type": "SELL",
    "post_tax": false,
    "client_reference": "",
    "initiation_flow": "API",
    "orders": [
      {
        "id": "e7aecb80-5e84-4bf7-984b-b39ab77eb0a8",
        "side": "SELL",
        "status": "NEW"
      },
      {
        "id": "eb5ba93f-5dfe-4bf1-8571-4da0caacc80c",
        "side": "SELL",
        "status": "PROCESSING"
      },
      {
        "id": "d8a85120-2941-4ed6-8d57-e80401a4779c",
        "side": "SELL",
        "status": "FILLED"
      }
    ]
  },
  "webhook_id": "cd2e4183-4e62-4e0f-981b-44b594d14610"
}

The above example shows a portfolio sell order consisting of three individual orders. The portfolio order is still in the PROCESSING state as not all individual orders have been fully executed yet.

Note that each individual order in a portfolio order goes through its own distinct lifecycle.

To get detailed information about any of the individual orders, call

GET /orders/{order_id}