Understanding portfolio orders

In this guide, you will find all the information you need to understand how portfolio orders are processed in the Investment API and how to best implement portfolio orders in your application.

How portfolio orders work

In the "Enabling portfolio investments" guide, we discussed how you can place the first portfolio buy order. In this guide, we will take a closer look at the inner workings of a portfolio order, discuss its properties, and define how you can interact with this object throughout its lifecycle.

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 individual order is processed as described in this order's guide.

This granularity of order management provides full visibility into order processing and enables advanced portfolio management use cases such as direct indexing.

Order types

In general, there are four types of portfolio orders that the Investment API supports: BUY, SELL, LIQUIDATION, and REBALANCING.

Nr.	Name	Type	Description
1	Nominal portfolio buy order	BUY	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.
2	Nominal portfolio sell order	SELL	A portfolio sell order always results in investments being sold according to the current allocation of the respective account. Nominal sell orders cannot exceed 90% of the NAV (net asset value) of the portfolio investment.
3	Full liquidation of the portfolio	LIQUIDATION	When a user's portfolio investments are fully liquidated, all individual instrument positions in the user's account are sold in full.
4	Rebalancing order	REBALANCING	A portfolio order of the type REBALANCING is created when a rebalancing is triggered for a particular account. It contains both buy and sell orders that when executed, realign the user’s portfolio investment with the desired target allocation.

Placing a nominal sell order

You can place a nominal sell order as follows: POST /portfolios/orders

Example request

{
	"user_id": "7c9dc9d0-8953-42f9-9b5e-f602a6201577",
	"account_id": "72ca4792-bd9c-4525-9f9b-c2ff93e1c352",
	"cash_amount": "400.00",
	"currency": "EUR",
	"side": "SELL"
}

Liquidating a portfolio

Liquidating a portfolio means that all positions held in the portfolio account in question are sold in their entirety. The account itself is not affected, it remains in an ACTIVE state and can be used for further investments. The management fees defined in the fee configuration are automatically deducted upon liquidation.

To initiate the liquidation of a user's portfolio investment, send the following request:

POST /portfolios/{account_id}/liquidation_request

Example request

{
	"user_id": "7c9dc9d0-8953-42f9-9b5e-f602a6201577"
}

In response to this example request, you will receive a portfolio_order_id. With this ID you can track the progress of the portfolio liquidation, as described in the next section.

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. Order checks have passed and the individual orders are executed.
FILLED	All individual orders have been executed successfully. The securities and cash positions have been updated accordingly.
CANCELLED	The 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 executed successfully, the portfolio order changes to the FILLED state.

Portfolio order object

Since we strive to make the overall order flow as transparent as possible, the portfolio order is designed as a nested object of individual orders, where each individual order can be queried for detailed information using our standard order engine.

To illustrate, let's look at an 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 PROCESSING state, as not all individual orders have been fully executed yet. It is important to 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, you can call GET /orders/{order_id} as described in the orders guide using order_ids.

Asynchronous order processing

The portfolio order processing flow is asynchronous, which means that upon submission of a new order you will receive a HTTP 202 Accepted and a portfolio_order_id. Further information about the progress of the portfolio order can be obtained either via webhooks or by directly fetching the portfolio order details via the API.

Webhooks

A webhook is sent for each state transition that the portfolio order undergoes in its lifecycle. An example webhook event looks as follows:

{
	"id": "54b8d84f-5bd0-4e43-bf0f-164388cb4c23",
	"created_at": "2021-07-21T14:10:00.000Z",
	"type": "PORTFOLIO_ORDER.NEW",
	"object": {
		"id": "eb5ba93f-5dfe-4bf1-8571-4da@caacc80c",
		"created_at": "2021-07-21T14:10:00.000Z",
		"updated_at": "2021-07-2114:10:00.000Z",
		"account_id": "alfcfbc7-6ba3-4ee0-b364-2da08e06264c",
		"allocation_id": "debf2026-f2da-4ff0-bb84-92e45babble3",
		"user_id": "2ef01903-3b0f-487c-89d8-303684d2f23c",
		"type": "SELL",
		"cash_amount": "1000",
		"currency": "EUR",
		"status": "PROCESSING",
		"orders": [
			{
				"id": "e7aecb80-5e84-4bf7-984b-b39ab77eb0a8",
				"side": "SELL", 
				"state": "NEW"
			},
			{
				"id": "eb5ba93f-5dfe-4bf1-8571-4da0caacc80c",
				"side": "SELL",
				"state": "PROCESSING"
			},
			{
				"id": "d8a85120-2941-4ed6-8d57-e80401a4779c",
				"side": "SELL",
				"state": "FILLED"
			}
		]
	},
	"webhook_id": "cd2e4183-4e62-4e0f-981b-44b594d14610"
}	

Furthermore, you will receive via webhook a sequence of events for each of the state transitions for all individual orders as described in this guide.

This provides full transparency and traceability of the lifecycle of not only the portfolio order, but also the lifecycles of all the individual orders that make up the portfolio order.

Tracing a portfolio order

This section summarises the sequence of events that allow you to track a portfolio order and its associated individual orders in their entirety.

1. Portfolio_order.NEW
   You receive this webhook when the portfolio order has been placed via the public API. It contains the generic order data, and an empty list of individual orders.
2. Portfolio_order.PROCESSING
   ou receive this webhook when the first individual order in the list is being executed, meaning that the state of the individual order changes from NEW to PROCESSING.
   • a) Individual_order.PROCESSING You receive this webhook for every individual order that changes state to PROCESSING.
   • b) Individual_order.FILLED You receive this webhook when an individual order is fully executed.
   • c) Steps a & b repeat until all individual orders are in state FILLED.
3. Portfolio_order.FILLED
   You receive this webhook when the portfolio order is executed in its entirety and the user's portfolio investment reflects the order request.

To make tracing and mapping of the individual orders as easy and seamless as possible, each individual order that is executed in step 3 carries the corresponding portfolio_order_id. The portfolio order id can be found in the client_reference field of the individual order object. See the respective API spec for further information.

Order cancellations

Portfolio orders can only be cancelled whilst in the NEW state. To cancel an existing order, call the cancellation endpoint with the appropriate portfolio_order_id, using DELETE /portfolios/orders/{portfolio_order_id}.

Upon successful cancellation of any portfolio order, you will receive a webhook notifying you about the cancellation.

What's next?

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