--- title: "Create a tax exemption" method: POST path: "/tax_exemptions" tags: ["Tax Exemptions"] --- # Create a tax exemption `POST /tax_exemptions` ## Request - Base URL: `https://sandbox.upvest.co` - URL: `https://sandbox.upvest.co/tax_exemptions` - Auth: OAuth 2 (client credentials, token URL `https://sandbox.upvest.co/auth/token`, scopes: `taxes:admin`) Creates a tax exemption order for end users who are resident in Germany for tax purposes. Upvest must hold the end user's Tax Identification Number before an exemption can be created. The request is processed asynchronously: the exemption is created with status `NEW` and moves to `ACTIVE`, which is signalled by a `TAX_EXEMPTION` webhook event. A single exemption covers exactly one `user_ids` entry and an allowance of up to €1,000 per tax year; a joint exemption requires exactly two entries and covers up to €2,000. See the [Creating a tax exemption order guide](https://docs.upvest.co/products/tol/guides/taxes/tax_exemptions_creating) for implementation details. ## Headers - `idempotency-key` string, uuid, required ## Request body - object: Request body for creating a tax exemption order for end users who are resident in Germany for tax purposes. - `user_ids` string[], required: Ids of the users for whom the tax exemption is to be created. - `tax_exemption_details` object, required: The German tax exemption details supplied when creating or updating a tax exemption order. - `tax_exemption_type` 'SINGLE' | 'MARRIED' | 'CIVIL_PARTNERSHIP': Tax exemption type * SINGLE - Tax exemption for Individual. * MARRIED - Tax exemption for married couples. * CIVIL_PARTNERSHIP - Tax exemption for registered civil partnerships. - `tax_exemption_amount` object, required: A monetary amount relating to a tax exemption order, with its [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency. - `amount` string, required: A positive cash amount, as a decimal string with up to two decimal places. - `currency` 'EUR' | 'GBP', required: Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code. * EUR — Euro. * GBP — Pound Sterling. - `country` string, required: Country code. [ISO 3166 alpha-2 Codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2). - `valid_to_date` string, date: Date until which the tax exemption is valid. If it is unlimited, it is omitted. For Germany it is always the last day of the year (YYYY-12-31). [RFC 3339, section 5.6](https://json-schema.org/draft/2020-12/json-schema-validation.html#RFC3339) ## Response `202` Creation request accepted. - object: A tax exemption order under German tax law. Records the allowance granted, the amounts used and remaining for the tax year, and the period for which the exemption is valid. - `id` string, uuid, required: The unique identifier of the tax exemption order, as a UUID. - `created_at` string, date-time, required: Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html) - `updated_at` string, date-time, required: Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html) - `status` 'NEW' | 'ACTIVE' | 'EXPIRED' | 'CANCELLED', required: Tax exemption status * NEW - The tax exemption request is created. * ACTIVE - The tax exemption is valid and active for the current year. * EXPIRED - The tax exemption is no longer `ACTIVE` and the `valid_to_date` already lies in the past. An update is not possible. * CANCELLED - The tax exemption could not be created or was cancelled. - `user_ids` string[], required: Ids of the users for whom the tax exemption was created. - `country` string, required: Country code. [ISO 3166 alpha-2 Codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2). - `valid_from_date` string, date, required: Date from which the tax exemption is valid. [RFC 3339, section 5.6](https://json-schema.org/draft/2020-12/json-schema-validation.html#RFC3339) - `valid_to_date` string, date, nullable, required: Date until which the tax exemption is valid. If it is unlimited, it is omitted. For Germany it is always the last day of the year (YYYY-12-31). [RFC 3339, section 5.6](https://json-schema.org/draft/2020-12/json-schema-validation.html#RFC3339) - `tax_exemption_details` object, required: The German tax exemption details returned for a tax exemption order, including the allowance granted and the amounts used and remaining for the tax year. - `tax_exemption_type` 'SINGLE' | 'MARRIED' | 'CIVIL_PARTNERSHIP', required: Tax exemption type * SINGLE - Tax exemption for Individual. * MARRIED - Tax exemption for married couples. * CIVIL_PARTNERSHIP - Tax exemption for registered civil partnerships. - `tax_exemption_amount` object, required: A monetary amount relating to a tax exemption order, with its [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency. - `amount` string, required: A positive cash amount, as a decimal string with up to two decimal places. - `currency` 'EUR' | 'GBP', required: Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code. * EUR — Euro. * GBP — Pound Sterling. - `utilized_amount` object, required: A monetary amount relating to a tax exemption order, with its [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency. - `amount` string, required: A positive cash amount, as a decimal string with up to two decimal places. - `currency` 'EUR' | 'GBP', required: Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code. * EUR — Euro. * GBP — Pound Sterling. - `remaining_amount` object, required: A monetary amount relating to a tax exemption order, with its [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency. - `amount` string, required: A positive cash amount, as a decimal string with up to two decimal places. - `currency` 'EUR' | 'GBP', required: Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code. * EUR — Euro. * GBP — Pound Sterling. ## Other responses - `400`: Bad Request. The incoming request had a malformed parameter/object. - `401`: Unauthorized. The caller has not been authenticated. - `403`: Forbidden. The caller has been authenticated but is not allowed to take the requested action. - `404`: Not Found. The requested resource could not be found. - `406`: Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. "Accept" header defined unsupported value. - `429`: Too Many Requests. The caller has exceeded their quota for the time period and has been throttled. - `500`: Internal Server Error. The service encountered an unexpected error. - `503`: Service Unavailable. The service handling for this request cannot be reached at this time. - `504`: Gateway Timeout. The service gateway has reached its internal timeout. ## Changes - **2026-09-16** `85aff1852bf8`: 10 info - added the new `CIVIL_PARTNERSHIP` enum value to the request property `tax_exemption_details/tax_exemption_type` - the response property `id` became required for the status `202` - added the required property `country` to the response with the `202` status - added the required property `created_at` to the response with the `202` status - …6 more [Operation history](https://skmtc.dev/upvest/apis/upvest-investment-api/changes/tax_exemptions/post.md) --- [API](https://skmtc.dev/upvest/apis/upvest-investment-api.md) · [All operations](https://skmtc.dev/upvest/apis/upvest-investment-api/llms.txt) · [OpenAPI document](https://skmtc.dev/upvest/apis/upvest-investment-api/revisions/ca69534b631d?raw)