Skip to content
Documentation
/
/
/
Tracking portfolio orders

Tracking portfolio orders

Prerequisites

Recommended: Track portfolio orders with webhooks

For portfolio order status, set up a webhook listener for portfolio and order events. You will receive automatic notifications as orders transition through their lifecycle and individual orders complete.

For more information, refer to Webhook event tracking

Portfolio order processing is handled asynchronously. When you submit a new order, you receive an HTTP 200 response and a portfolio_order_id. Your webhook handler will receive events as the portfolio order progresses.

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

In addition, you receive via webhook a sequence of events for each of the state transitions for all the individual orders as described in the orders lifecycle 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.

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 receive during the lifecycle of a portfolio order and its associated individual orders.

  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 event when the first individual order has been created and accepted for trading. The order has the status of NEW or a later status.
    • a) ORDER.NEW You receive this webhook for every individual order that is created.
    • b) ORDER.PROCESSING You receive this webhook for every individual order that changes state to PROCESSING.
    • c) 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 help you trace and map individual orders, 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.

You only receive webhooks for any given use case if you subscribe to the webhook topic as described in the Webhooks concept guide. The two relevant webhook topics that you need to subscribe to are ORDER and PORTFOLIO_ORDER.