# How to track tax collections

## Prerequisites

- **Authentication scopes** — `taxes: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 tax collection events.
  - Subscribe to [`TAX_COLLECTION.*`](/products/byol/guides/taxes/tax_collection_webhook) events.
For more information, refer to [Implementing webhooks](/products/byol/getting_started/implementing_webhooks).


**Recommended: Track tax collections with webhooks**

The event-driven approach uses webhooks to notify you of status changes in real-time, ensuring you never miss critical events such as sell-to-cover orders, tax payments, or cancellations.

For more information, refer to [Tax collection webhook events](/products/byol/guides/taxes/tax_collection_webhook)

## Webhook-based tracking (recommended approach)

Subscribe to tax collection events to receive real-time notifications as the process unfolds:

- **`TAX_COLLECTION.*` events** — Tax preparation, completion, and cancellation statuses
- **Order and execution events** — Sell-to-cover orders (identified by `initiation_flow: SELL_TO_COVER_TAXES`)
- **Position and cash balance updates** — Reflect the impact of sell-to-cover and tax payments
- **Transaction events** — Detailed breakdown of tax amounts and transaction types


This webhook-based approach removes the need to poll and provides complete visibility into the tax collection process.

## Related tracking mechanisms (reference)

Additional data sources are available if needed:

### Sell-to-cover orders events

In the case of multiple accounts holding the same instrument within an account group, Upvest will select the account with the largest position to trigger the sell-to-cover order. Due to unexpectedly high taxes on the order proceeds, there may be more than one sell-to-cover per tax collection.

Example order event
```json

{
  "id": "8962b496-8d42-4560-bfab-10490dd1a721",
  "created_at": "2021-07-21T14:10:00.00Z",
  "type": "ORDER.NEW",
  "object": {
    "id": "1f5758d3-1ef7-4b4c-96ec-6b3da2bf1a8a",
    "created_at": "2021-07-21T14:10:00.00Z",
    "updated_at": "2021-07-21T14:10:00.00Z",
    "user_id": "2dedfeb0-58cd-44f2-ae08-0e41fe0413d9",
    "account_id": "debf2026-f2da-4ff0-bb84-92e45babb1e3",
    "cash_amount": "10.00",
    "currency": "EUR",
    "side": "SELL",
    "instrument_id": "US0378331005",
    "instrument_id_type": "ISIN",
    "order_type": "MARKET",
    "quantity": "0.05",
    "user_instrument_fit_acknowledgement": true,
    "limit_price": "",
    "stop_price": "",
    "status": "NEW",
    "fee": "0.0",
    "executions": [],
    "client_reference": "",
    "initiation_flow": "SELL_TO_COVER_TAXES"
  },
  "webhook_id": "9df39835-be87-4243-9018-f2500b39cee6"
}
```

| Parameter | Description |
|  --- | --- |
| `initiation_flow` | The value `SELL_TO_COVER_TAXES` indicates tax collection by this method. |


### Transactions reporting

Example transaction reporting event
```json
{
  "id": "1d27576e-f4a3-11ed-a05b-0242ac120003",
  "created_at": "2023-01-01T00:00:00Z",
  "type": "CASH_TRANSACTION.EXECUTED",
  "object": {
    "account_group_id": "6409e3f2-8835-11ed-96a4-2eabd0c03f8a",
    "booking_date": "2023-01-01T00:00:00Z",
    "created_at": "2023-01-01T00:00:00Z",
    "delta": {
      "amount": "-9.70",
      "currency": "EUR"
    },
    "id": "2349857c-f4a3-11ed-a05b-0242ac120003",
  "instrument": {
      "uuid": "ccb86937-8a39-4160-8d33-85bf9e902321",
      "isin": "US0378331005"},
    "references":  [ 
{
          "id": "7579a672-8835-11ed-9455-2eabd0c03f8a",
          "type": "TAX_TRANSACTION"
        }
],
    "taxes": [
       {
          "amount": "9.70",
          "currency": "EUR",
          "type": "TOTAL"
        }
],
    "type": "TAX_PREPAYMENT_DE",
    "updated_at": "2023-01-01T00:00:00Z",
    "value_date": "2023-01-01T00:00:00Z"
  },
  "webhook_id": "1216067c-f4a3-11ed-a05b-0242ac120003"
}
```

| Parameter | Description |
|  --- | --- |
| `type` | `TAX_PREPAYMENT_DE`: German tax prepayment (Vorabpauschale). The reports are created in the clients' branding and contain a detailed breakdown of the various tax amounts. |
| `type` | `TAX_PREPAYMENT_DE_CANCELLATION`: German tax prepayment (Vorabpauschale) cancellation. This report is created when the automated tax collection is not successful following multiple retry attempts to collect. This occurs, for example, when the end user does not have sufficient open positions or cash balances to complete the process. |


### Example tax collection report

### Example tax collection cancellation report