Skip to content
Documentation
/
/
/
Tracking portfolio orders

Tracking portfolio orders

Portfolio order processing is handled asynchronously. When you submit a new order, you receive an HTTP 202 Accepted and a portfolio_order_id, but you must obtain further information about the portfolio order's progress 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.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 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 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.

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}