Tax Exemptions

Create a tax exemption

Changed on

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 for implementation details.

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)

Headers

idempotency-keystring uuid required
Example:ccb07f42-4104-44ad-8e1f-c660bb7b269c

A UUID to be used as an idempotency key. This prevents a duplicate request from being replayed. https://docs.upvest.co/documentation/concepts/api_concepts/idempotency

Request body

user_idsstring[] required

Ids of the users for whom the tax exemption is to be created.

countrystring required

Country code. ISO 3166 alpha-2 Codes.

valid_to_datestring 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

Response

Creation request accepted.

idstring uuid required

The unique identifier of the tax exemption order, as a UUID.

created_atstring date-time required

Date and time when the resource was created. RFC 3339-5, ISO8601 UTC

updated_atstring date-time required

Date and time when the resource was last updated. RFC 3339-5, ISO8601 UTC

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_idsstring[] required

Ids of the users for whom the tax exemption was created.

countrystring required

Country code. ISO 3166 alpha-2 Codes.

valid_from_datestring date required

Date from which the tax exemption is valid. RFC 3339, section 5.6

valid_to_datestring 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

Changes

  • 85aff1852bf8Revision changes
    • info

      added the new CIVIL_PARTNERSHIP enum value to the request property /

    • info

      the response property became required for the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status