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.
CANCELLEDThe portfolio order has been cancelled by you or due to an error at the trading partner.

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": "10bfd760-dbf0-4302-b415-7ac7ffec7a52",
	"created at": "2021-07-21T14:10:00.000Z",
	"updated_at": "2021-07-21T14:10:00.000Z",
	"account_id": "d7a57c3e-2be9-4c4e-b3ff-48e1e7815659",
	"allocation_id": "214fad90-42dd-40b5-8f78-53fcde53cd6f",
	"user_id": "2ef01903-3b0f-487c-89d8-303684d2f23c",
	"type": "SELL",
	"cash_amount": "1000",
	"currency": "EUR",
	"status": "PROCESSING",
	"orders" : [
		{
			"id": "6a8c5a23-@bff-4faf-83bb-6c4871110409",
			"side": "SELL",
			"state":"NEW"
		},
		{
			"id": "5e6dc328-7add-4ad6-9626-8f691b0369cc",
			"side": "SELL",
			"state": "PROCESSING"
		},
		{
			"id": "d35f1d8c-675f-45d9-9689-48db5ed174aa",
			"side": "SELL",
			"state": "FILLED"
		}
	]
}

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

INFO

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}](/api/Orders/#retrieve-an-order)

Further Reading

What's next?

Now that you have mastered portfolio orders, you can continue by learning how to trigger a rebalancing for users' portfolio investments.

Was this page helpful?

On this page