Tracking portofolio orders

Portfolio order processing is handled asynchronously. This means that, when you successfully submit a new order, you will receive an HTTP 202 Accepted and a portfolio_order_id, but further information about the progress of the portfolio order must be obtained by handling 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 of all the individual orders that make up the portfolio order.

WARNING

Webhooks notify you of events in business processes, not the success or failure of the initialisation of those processes.

Please be sure to check the HTTP status of the response to your requests and handle failure cases appropriately.

Sequence of events

The following sequence of events are a summary of those that you will receive during the lifecycle of a portfolio order and its associated individual orders.

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.
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.
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.

Polling for the status of a portfolio order.

You can get the state of a portfolio order at any time by issuing the following request.

GET /portfolios/orders/{portfolio_order_id}