Understanding portfolio orders

In the 'Enabling portfolio investments' guide, we discussed how you can place the first portfolio buy order.

In this section, 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 during its lifecycle.

How portfolio orders work

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.

You can track the progress of a portfolio order at any time by

GET /portfolios/orders/{portfolio_order_id}

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"
}

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}

Asynchronous order processing

Portfolio order processing is asynchronous, which means that when you submit a new order, you will receive an 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 goes through in its lifecycle.

Example webhook event

{
	"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"
}

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

This allows full transparency and traceability of the lifecycle not only of 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
    You 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.NEW You receive this webhook for every individual order that is created.
    • b) Individual_order.PROCESSING You receive this webhook for every individual order that changes state to PROCESSING.
    • c) Individual_order.FILLED You receive this webhook when an individual order is fully executed.
    • d) 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. You can find the portfolio order ID in the client_reference field of the individual order object. See the respective API spec for further information.


INFO

You will only receive webhooks for any given use case if you subscribe to the webhook topic as discussed here. The two relevant webhook topics that you need to subscribe to are ORDER and PORTFOLIO_ORDER.


Cancelling an order

Portfolio orders can only be cancelled whilst in the NEW state. To cancel an existing order, send the following request using the portfolio_order_id of the order you want to cancel:

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.

Was this page helpful?

On this page