Skip to content
Documentation
/
/
/
Create Tax Exemption Orde...

Creating a tax exemption order

Prerequisites

  • Authentication scopes — taxes:admin

    For more information, refer to Authentication scopes.

  • Webhook handler ready — Set up a webhook endpoint to listen for tax exemption status updates.

    For more information, refer to Implementing webhooks.

  • Fully onboarded user — The user that is part of a German tax exemption must meet the following requirements:

    • The user is a German tax resident and has completed user tax onboarding.
    • The user must have a valid Tax Identification Number (TIN).

The tax exemption status transitions from NEW to ACTIVE when you receive the corresponding webhook event. Monitor these events to track activation progress.

For more information, refer to Tax exemption webhook events

Creating a tax exemption

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

POST /tax_exemptions

Example

{
  "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": "2026-12-31"
}

The request body contains the following:

ParameterDescriptionExample value
user_idsRequired: The user ID in an array.

The tax exemption applies to all account groups belonging to the user.

There can only ever be one user ID per tax exemption.		70821d79-366f-4873-804b-14857d690496
tax_exemption_amount.amountRequired: The amount of tax exemption applied for.

From tax year 2023, the maximum amount of tax exemption is €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.currencyRequired: The currency of the requested tax exemption amount.

NOTE: Only euros are currently supported.

Valid parameter: EUR.		EUR
countryRequired: The tax country code encapsulates the respective tax country.

NOTE: Only German tax exemptions are currently supported.

Valid parameter: DE		DE
tax_exemption_details.tax_exemption_typeSet equal to SINGLE.SINGLE
valid_to_dateOptional: The date (RFC 3339, section 5.6) until which the tax exemption is valid. Omit this field if the validity is unlimited.2028-12-31



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.