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:

Type	Name	Description
`BUY`	Nominal portfolio buy order	Nominal 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.
`SELL`	Nominal portfolio sell order	A 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.
`REBALANCING`	Rebalancing order	A 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:

State	Description
`NEW`	A portfolio order has been placed, relevant checks are being conducted.
`PROCESSING`	All individual orders have been created. The order checks have been passed and the individual orders are being processed.
`FILLED`	All individual orders have been successfully executed. The securities and cash positions have been updated accordingly.
`SETTLED`	A portfolio order switches to this status when all individual orders have also been settled.
`CANCELLED`	Rebalancing execution orders can be cancelled for various reasons. All possible cases are listed in the table below.

Cancellation reasons

Cancellation reason	Description
`ACOUNT_IS_EMPTY`	The account has no positions.
`ACCOUNT_NOT_FOUND`	The portfolio account was not found.
`CANCELLED_BY_CLIENT`	Cancellation at the customer's request.
`CANCELLED_BY_UPVEST`	Cancelled by Upvest.
`CONFIGURATION_IS_MISSING`	The account has no portfolio configuration.
`INVALID_ACCOUNT_TYPE`	A rebalancing on a trading account is not allowed.
`PORTFOLIO_IS_BALANCED`	The 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_STATUS`	The 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}