Skip to content
Documentation/
/
/
How to Track Tax Collecti...

How to track tax collections

The investment API provides complete transparency over the tax collection process, via:

This section gives you an overview of these options.

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.


{
  "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"
}
ParameterDescription
initiation_flowThe value SELL_TO_COVER_TAXES indicates tax collection by this method.

Transactions reporting

{
  "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"
}
ParameterDescription
typeTAX_PREPAYMENT_DE: German tax prepayment (Vorabpauschale). The reports are created in the clients' branding and contain a detailed breakdown of the various tax amounts.
typeTAX_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