# Tracking portfolio orders

## Prerequisites

- **Authentication scopes** — `orders:read`, `portfolios:read`
For more information, refer to [Authentication scopes](/products/byol/concepts/api_concepts/authentication/authentication_oauth#list-of-authentication-scopes).
- **Webhook handler ready** — Set up a webhook endpoint to listen for portfolio order events.
  - Subscribe to [`PORTFOLIO_ORDER.*` and `ORDER.*`](/products/byol/guides/orders/orders_webhooks) events.
For more information, refer to [Implementing webhooks](/products/byol/getting_started/implementing_webhooks).


**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](/products/byol/guides/orders/orders_webhooks)

## Webhook-based tracking (recommended approach)

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

```json
{
  "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](/products/byol/guides/orders).

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](/api_errors/) 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](/api/orders/retrieve_order) 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](/products/byol/concepts/api_concepts/webhooks). The two relevant webhook topics that you need to subscribe to are `ORDER` and `PORTFOLIO_ORDER`.