# Retrieving acquisition costs

## Prerequisites

* **Authentication scopes** — `positions_performance: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 receive position and valuation notifications.
  * Subscribe to [`ACCOUNT_POSITION_PERFORMANCE.*`](/products/byol/guides/positions/positions_webhooks) events.
For more information, refer to [Implementing webhooks](/products/byol/getting_started/implementing_webhooks).


Once you have an active user with an account group and a corresponding open account, you can query positions for the account.

## Acquisition costs best practices

We recommend retrieving the account-level view of acquisition costs for the end user. This approach allows you to list the acquisition costs for **all positions in an account** in a single request.

This provides the most informative view for end users and aids in calculating unrealised gains and losses across the whole account. Use it for the initial load of your system and whenever you need guaranteed full-account consistency.

The instrument-level view is available when you need the details of a single position in an account.

## Request acquisition costs for all positions in an account

### Example request for an account's position performance

Submit a `GET` request with just the `account_id` in the request path. The endpoint returns the following in the response.

Request
```http
GET /accounts/{account_id}/positions_performance
```

#### Request path parameter

| **Path parameter** | **Description** |
|  --- | --- |
| `account_id` | The unique identifier of the account. Universally Unique Identifier (UUID). |


### Example response for an account's position performance

Response
```json
{
  "meta": {
    "offset": 0,
    "limit": 100,
    "count": 2,
    "total_count": 2
  },
  "data": [
    {
      "account_id": "f1410edd-c2c8-457b-82e6-ef833700041d",
      "account_group_id": "73b20f1a-8cdd-4b9e-8fdb-eefc719b4ebb",
      "instrument": {
        "uuid": "40d850c5-d9b5-4da8-b5f8-520ad3a0b614",
        "isin": "DE0007664005"
      },
      "acquisition_cost": {
        "calculated_at": "2026-07-02T13:10:00.00Z",
        "total_quantity": "11",
        "total_cost": {
          "amount": "375.50",
          "currency": "EUR",
          "quantity": "5"
        },
        "pending_cost_quantity": "6"
      }
    },
    {
      "account_id": "f1410edd-c2c8-457b-82e6-ef833700041d",
      "account_group_id": "73b20f1a-8cdd-4b9e-8fdb-eefc719b4ebb",
      "instrument": {
        "uuid": "16bf56e5-84df-466d-a0b2-7a159e3c9e22",
        "isin": "LU0274208692"
      },
      "acquisition_cost": {
        "calculated_at": "2025-04-11T10:11:00.00Z",
        "total_quantity": "3",
        "total_cost": {
          "amount": "360.00",
          "currency": "EUR",
          "quantity": "3"
        },
        "pending_cost_quantity": "0"
      }
    }
  ]
}
```

**In the example above:**

For the first instrument:

- The end user holds `11` units in total as shown in the `total_quantity`.
- The acquisition cost is known for `5` units (`total_cost.quantity`).
- The total acquisition cost for the known quantity is `EUR 375.50` (`total_cost.amount`).
- For the remaining `6` units (`pending_cost_quantity`), the acquisition cost data is still outstanding.


For the second instrument:

- The end user holds `3` units in total as shown in the `total_quantity`.
- The acquisition cost is known for `3` units (`total_cost.quantity`).
- The total acquisition costs for the known amount equals `EUR 360.00` (`total_cost.amount`).
- There are `0` remaining units (`pending_cost_quantity`), so the acquisition cost data is complete.


## Request acquisition costs for a specific instrument in an account

### Example request for the position performance of an instrument

Submit a `GET` request that includes both the `account_id` and the `instrument_id` in the request path:

Request
```http
GET /accounts/{account_id}/positions/{instrument_id}/performance
```

#### Request path parameters

| **Path parameter** | **Description** |
|  --- | --- |
| `account_id` | The unique identifier of the account. Universally Unique Identifier (UUID). |
| `instrument_id` | The instrument's Universally Unique Identifier (UUID) or International Securities Identification Number (ISIN). Prefix this value with either 'uuid:' or 'isin:' as defined by the [URN scheme](https://datatracker.ietf.org/doc/html/rfc8141). |


### Example response for the position performance of an instrument

The endpoint returns the following in the response.

Response
```json
{
  "account_id": "f1410edd-c2c8-457b-82e6-ef833700041d",
  "account_group_id": "73b20f1a-8cdd-4b9e-8fdb-eefc719b4ebb",
  "instrument": {
    "uuid": "40d850c5-d9b5-4da8-b5f8-520ad3a0b614",
    "isin": "DE0007664005"
  },
  "acquisition_cost": {
    "calculated_at": "2026-07-02T13:10:00.00Z",
    "total_quantity": "11",
    "total_cost": {
      "amount": "375.50",
      "currency": "EUR",
      "quantity": "5"
    },
    "pending_cost_quantity": "6"
  }
}
```

**In the example above:**

- The end user holds `11` units in total as shown in the `total_quantity`.
- The acquisition cost is known for `5` units (`total_cost.quantity`).
- The total acquisition costs for the known amount equals `EUR 375.50` (`total_cost.amount`).
- For the remaining `6` units (`pending_cost_quantity`), the acquisition cost data is still outstanding.


## Acquisition costs response fields

| **Field** | **Description** |
|  --- | --- |
| `account_id` | The account's unique identifier. |
| `account_group_id` | The account group's unique identifier. |
| `instrument.uuid` | The instrument's Universally Unique Identifier (UUID), defined by [RFC 4122](https://datatracker.ietf.org/doc/html/rfc4122). |
| `instrument.isin` | The instrument's International securities identification number defined by [ISO 6166](https://en.wikipedia.org/wiki/International_Securities_Identification_Number). |
| `acquisition_cost.calculated_at` | The date and time the acquisition costs were last calculated. |
| `acquisition_cost.total_quantity` | The total quantity of the position in the instrument. This is the sum of the quantity with known acquisition costs (`total_cost.quantity`) and the quantity with pending acquisition costs (`pending_cost_quantity`). |
| `acquisition_cost.total_cost.amount` | The total known acquisition cost of the position, including all fees, taxes, and additional costs. This amount covers only the quantity in `total_cost.quantity`. |
| `acquisition_cost.total_cost.currency` | The alphabetic, three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code for the `total_cost.amount`. `EUR` - Euro, `GBP` - Pound Sterling |
| `acquisition_cost.total_cost.quantity` | The quantity of the position for which the acquisition cost is known and included in `total_cost.amount`. |
| `acquisition_cost.pending_cost_quantity` | The quantity of the position for which the acquisition cost is not yet available. This reflects, for example, units transferred in while the Taxbox file or client-provided cost data is still outstanding. Once the data is received, these units move into `total_cost.quantity`. |


## Track updates using the positions performance webhook events

Store the resulting values in your system to quickly provide access to the end users. You can listen for the positions performance webhook events to update the values in your system.