Creating a tax exemption order

Prerequisites

In order to create a new tax exemption, Upvest must have the user’s Tax Identification Number (TIN).

To submit a tax exemption request, execute the following request:

POST /tax_exemptions/

Example request

{
  "user_ids": [
    "70fd317b-81e1-4f21-9f7e-3b5cb4dfe686"
  ],
  "tax_exemption_details": {
    "tax_exemption_type": "SINGLE",
    "tax_exemption_amount": {
      "currency": "EUR",
      "amount": "1000"
    }
  },
  "country": "DE",
  "valid_to_date": "2024-12-31"
}

The request body contains the following:

Parameter	Description	Example value
`user_ids`	Required: One or more user IDs in an array. The tax exemptions apply to all account groups belonging to the respective user or pair. There can only ever be one user ID for a single tax exemption type. The main use case for submitting an array of `user_ids` is to create a joint tax exemption for a married couple.	`70821d79-366f-4873-804b-14857d690496`
`tax_exemption_amount.amount`	Required: The amount of tax exemption applied for. From tax year 2023, the maximum amount of tax exemption for a single tax exemption is EUR 1,000. Valid parameter range: ["0.01", "1000.00"] The value is a number in the form of a character string.	`1000.00`
`tax_exemption_amount.currency`	Required: The currency of the requested tax exemption amount. NOTE: Only euros are currently supported.Valid parameter: `EUR`.	`EUR`
`country`	Required: The tax country code encapsulates the respective tax country. NOTE: Only German tax exemptions are currently supported.Valid parameter: `DE`	`DE`
`tax_exemption_type`	Required: The type of tax exemption determines the maximum tax exemption amount.NOTE: Currently, only tax exemptions for individuals are supported.Valid parameter: `SINGLE`	`SINGLE`
`valid_to_date`	Required: The date (RFC 3339, section 5.6) until which the tax exemption is valid. If the validity is unlimited, the date is omitted.	`2024-12-31`

Example response

{
  "id": "f1a57a04-1a89-4dab-ae3a-ff9b2a9377c1"
}

The ID in the response is the ID of the tax exemption created.

Note that the tax exemption is only active when a response indicating its activation is received via a webhook. At this current stage of the process, it still has the status NEW.

Request rejected

The API can discard a request before it is accepted for downstream processing.

This happens if it does not pass the validation of the input data and additional internal consistency checks. Reasons for such behaviour can be, for example, missing parameters or if the requested tax exemption amount exceeds the maximum amount.

Read also the webhooks section of this guide.