Authentication scopes —
taxes:readFor more information, refer to Authentication scopes.
Webhook handler ready — Set up a webhook endpoint to listen for tax collection events.
- Subscribe to
TAX_COLLECTION.*events.
For more information, refer to Implementing webhooks.
- Subscribe to
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
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.
Additional data sources are available if needed:
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"
}| Parameter | Description |
|---|---|
initiation_flow | The value SELL_TO_COVER_TAXES indicates tax collection by this method. |
{
"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. |
