# Acquisition costs

Acquisition cost of a position is the total expense incurred to purchase an instrument including the base purchase price plus all associated fees and taxes.

Acquisition cost data is used to calculate unrealised gains and losses of an investment on an individual position level, as well as on the account/portfolio level.

Acquisition costs are available through the positions performance endpoints.

## Our solution for Acquisition costs

| **Functionality** | **Related endpoint** |
|  --- | --- |
| Request acquisition costs | Send a `GET` request to `/accounts/{account_id}/positions_performance` for an entire account or `/accounts/{account_id}/positions/{instrument_id}/performance` for a specific instrument. |
| Positions performance events | Use the Positions performance events webhook to automatically receive a notification when a position's acquisition costs are updated due to a buy/sell order, securities transfer, or a corporate action. |


## What are acquisition costs?

Acquisition costs reflect the total amount an end user paid to acquire a position in an instrument, including purchase price, fees, and taxes. Acquisition costs do not show the current market value of a position. The primary use case for acquisition costs is displaying unrealised gains and losses to end users, either at the account level or for an individual instrument:

```
Unrealised gain/loss = (quantity × current market price) − acquisition cost
```

The Acquisition Costs API provides the `quantity` and `acquisition cost` values. You can source the current market price of an instrument from your market data provider or the Upvest price data or [account valuations flow](/products/byol/guides/positions/valuations).

For access to real-time instrument prices and account valuations, you must include the Upvest Market Data Package as part of your Upvest contract. Refer to the [Instruments guide](/products/byol/guides/instruments/concept) for more details.

Displaying unrealised gains/losses gives end users a clear view of their investment performance.

## What impacts acquisition costs?

Acquisition costs are updated when units are added to or removed from a position or in case of certain corporate actions. The following events impact a position's acquisition cost.

### Buys and sells

* **Buy**: When an end user buys units of an instrument, the acquisition cost of the position increases by the total amount paid, including fees and taxes. This change is reflected as an increase in the `total_cost.quantity` and `total_cost.amount` fields.
* **Sell**: When an end user sells units, the corresponding acquisition cost is removed from the position and used to calculate the realised gain or loss for that sale. This change is reflected as a decrease in the `total_cost.quantity` and `total_cost.amount` fields.


### Transfers

When an end user transfers a position into their Upvest account, the acquisition cost data must accompany the transferred units. How this data arrives depends on where the transfer originates.

#### Transfers within Germany

For transfers within Germany, acquisition cost data is exchanged automatically via the standardised Taxbox file exchange. The Taxbox file typically arrives up to two weeks after the units themselves. Until it arrives, the transferred units are reported in the `pending_cost_quantity` field (see [Management of pending acquisition costs](#management-of-pending-acquisition-costs)).

#### Cross-border transfers

Countries outside of Germany handle cross-border transfers in different ways. For these transfers, clients can request the acquisition cost details from the end user and forward this information to Upvest.

* If the position was acquired in multiple tranches, you must provide the specific cost details for each tranche.
* You can submit the data directly to Upvest via a Zendesk ticket.


Until the data is received and processed, the transferred units remain in the `pending_cost_quantity` field (see [Management of pending acquisition costs](#management-of-pending-acquisition-costs)).

#### Management of pending acquisition costs

Units received without acquisition cost data are reported as the `pending_cost_quantity`. Once the Taxbox file or the client-provided data is received and processed:

1. The acquisition cost data is updated.
2. The affected units move into the known-cost quantity (`total_cost.quantity`).
3. The `pending_cost_quantity` is reduced accordingly (to zero once all costs are reported and processed).


An `ACCOUNT_POSITION_PERFORMANCE.UPDATED` webhook event notifies you of the change.

### Corporate actions

Corporate actions can change the composition of a position and impact the acquisition cost data. The following scenarios can occur:

* **New units with zero or non-zero acquisition costs**: Depending on the corporate action, end users may receive new units with a valid acquisition cost of zero or with a non-zero acquisition cost. A typical example of such a corporate action is a Bonus issue.
It is essential to distinguish between:
  * a **zero acquisition cost**, which is a valid, known value for certain corporate actions and is included in `total_cost.quantity`, and
  * an **absent acquisition cost**, which is reported in `pending_cost_quantity` until the value is provided. These units typically appear as a result of incoming security transfers.
* **Removal of units**: A corporate action can remove units from a position, in which case the associated acquisition cost is removed as well.
* **Stock splits and reverse stock splits**: The total acquisition cost of the original quantity remains unchanged, but the quantity and cost per unit are adjusted proportionally: cost per unit decreases for a stock split and increases for a reverse stock split, according to the split ratio.
* **Retroactive corrections**: In rare cases, issuers may retroactively update the acquisition costs assigned by a corporate action after the initial assignment. When this occurs, Upvest corrects the data and resends the corresponding webhook event with the same event ID.


## What does not impact acquisition costs?

The following do **not** change a position's acquisition cost:

* **Vorabpauschale (advance lump-sum tax) payments**: These tax prepayments affect the tax base for a later sale of the position, but they do not change the acquisition cost itself.
* **Market price changes**: Changes in the market price of an instrument affect the position's current valuation, not its acquisition cost.