Taxes

Tax Exemptions

Download Spec

All tax exemptions related paths

post/tax_exemptions

Create a tax exemption

Creates a tax exemption.

user_idsarray

required

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

User unique identifier.

Format: uuid

tax_exemption_detailsobject (Tax Exemption - Request - German Tax Exemption Details)

required

tax_exemption_typestring

Tax exemption type

SINGLE - Tax exemption for Individual.
MARRIED - Tax exemption for married couples.

Enum: SINGLE
MARRIED

tax_exemption_amountobject (Tax Exemption - Create - Request - Tax Exemption Details - Amount)

required

countrystring

required

Country code. ISO 3166 alpha-2 Codes.

Pattern: ^[A-Z]{2}$

valid_to_datestring

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

Format: date

Responses

Request examples

{
  "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"
}

Response examples

Creation request accepted.

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

get/tax_exemptions/{tax_exemption_id}

Get a tax exemption by ID

Returns the tax exemption specified by its ID

tax_exemption_idstring

required

Format: uuid

Responses

Response examples

{
  "id": "f1a57a04-1a89-4dab-ae3a-ff9b2a9377c1",
  "created_at": "2024-01-01T10:33:43Z",
  "updated_at": "2024-01-01T10:33:43Z",
  "status": "ACTIVE",
  "user_ids": [
    "70821d79-366f-4873-804b-14857d690496"
  ],
  "country": "DE",
  "valid_from_date": "2024-01-01",
  "valid_to_date": "2024-12-31",
  "tax_exemption_details": {
    "tax_exemption_type": "SINGLE",
    "tax_exemption_amount": {
      "amount": "1000.00",
      "currency": "EUR"
    },
    "utilized_amount": {
      "amount": "0.00",
      "currency": "EUR"
    },
    "remaining_amount": {
      "amount": "1000.00",
      "currency": "EUR"
    }
  }
}

put/tax_exemptions/{tax_exemption_id}

Update a tax exemption

Updates a tax exemption specified by its ID.

user_idsarray

required

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

User unique identifier.

Format: uuid

tax_exemption_detailsobject (Tax Exemption - Request - German Tax Exemption Details)

required

tax_exemption_typestring

Tax exemption type

SINGLE - Tax exemption for Individual.
MARRIED - Tax exemption for married couples.

Enum: SINGLE
MARRIED

tax_exemption_amountobject (Tax Exemption - Create - Request - Tax Exemption Details - Amount)

required

countrystring

required

Country code. ISO 3166 alpha-2 Codes.

Pattern: ^[A-Z]{2}$

valid_to_datestring

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

Format: date

Responses

Request examples

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

Response examples

The tax exemption update is submitted.

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

delete/tax_exemptions/{tax_exemption_id}

Delete a tax exemption

Deletes a tax exemption specified by its ID.

tax_exemption_idstring

required

Format: uuid

Responses

Response examples

The request has been successfully accepted and will be processed asynchronously.

Empty response

get/users/{user_id}/tax_exemptions

List tax exemptions for a user

Returns the tax exemptions of the user specified by ID.

sortstring

Sort the result by created_at.

Default: "created_at"
Enum: created_at

orderstring

Sort order of the result list if the sort parameter is specified. Use ASC for ascending or DESC for descending sort order.

Default: "ASC"
Enum: ASC
DESC

offsetint

Use the offset argument to specify where in the list of results to start when returning items for a particular query.

Format: int32
Min: 0

limitint

Use the limit argument to specify the maximum number of items returned.

Format: int32
Default: 100
Min: 0
Max: 1000

Responses

Response examples

{
  "meta": {
    "offset": 0,
    "limit": 100,
    "count": 1,
    "total_count": 1,
    "sort": "created_at",
    "order": "ASC"
  },
  "data": [
    {
      "id": "f1a57a04-1a89-4dab-ae3a-ff9b2a9377c1",
      "created_at": "2024-01-01T10:33:43Z",
      "updated_at": "2024-01-01T10:33:43Z",
      "status": "ACTIVE",
      "user_ids": [
        "70821d79-366f-4873-804b-14857d690496"
      ],
      "country": "DE",
      "valid_from_date": "2024-01-01",
      "valid_to_date": "2024-12-31",
      "tax_exemption_details": {
        "tax_exemption_type": "SINGLE",
        "tax_exemption_amount": {
          "amount": "1000.00",
          "currency": "EUR"
        },
        "utilized_amount": {
          "amount": "0.00",
          "currency": "EUR"
        },
        "remaining_amount": {
          "amount": "1000.00",
          "currency": "EUR"
        }
      }
    }
  ]
}

webhook

Tax Exemption Events

idstring

required

Event unique identifier

Format: uuid

created_atstring

required

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

Format: date-time

typestring

required

Tax exemption events webhook type

TAX_EXEMPTION.CREATED - Tax exemption successfully created.
TAX_EXEMPTION.UPDATED - Tax exemption successfully updated.
TAX_EXEMPTION.DELETED - Tax exemption successfully deleted.

Enum: TAX_EXEMPTION.CREATED
TAX_EXEMPTION.UPDATED
TAX_EXEMPTION.DELETED

objectobject (Webhook - Tax exemption - Created - Tax exemption)

required

idstring

required

Tax Exemption Unique Identifier

Format: uuid

created_atstring

required

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

Format: date-time

updated_atstring

required

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

Format: date-time

statusstring

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.

Enum: NEW
ACTIVE
EXPIRED
CANCELLED

user_idsarray

required

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

User unique identifier.

Format: uuid

countrystring

required

Country code. ISO 3166 alpha-2 Codes.

Pattern: ^[A-Z]{2}$

valid_from_datestring

required

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

Format: date

valid_to_datestring or null

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

Format: date

tax_exemption_detailsobject (Tax Exemption - German Tax Exemption Details)

required

webhook_idstring

required

Webhook unique identifier.

Format: uuid

Responses

Request examples

{
  "id": "295cf14f-368c-450e-b57e-48d115d30fe4",
  "created_at": "2024-01-01T10:34:43Z",
  "type": "TAX_EXEMPTION.CREATED",
  "object": {
    "id": "f1a57a04-1a89-4dab-ae3a-ff9b2a9377c1",
    "created_at": "2024-01-01T10:33:43Z",
    "updated_at": "2024-01-01T10:33:43Z",
    "status": "ACTIVE",
    "user_ids": [
      "70821d79-366f-4873-804b-14857d690496"
    ],
    "country": "DE",
    "valid_from_date": "2024-01-01",
    "valid_to_date": "2024-12-31",
    "tax_exemption_details": {
      "tax_exemption_type": "SINGLE",
      "tax_exemption_amount": {
        "amount": "1000.00",
        "currency": "EUR"
      },
      "utilized_amount": {
        "amount": "0.00",
        "currency": "EUR"
      },
      "remaining_amount": {
        "amount": "1000.00",
        "currency": "EUR"
      }
    }
  },
  "webhook_id": "4a80c45f-204c-4498-ac20-d900a846e166"
}

Response examples

Request has been processed successfully.

Empty response

webhook

Tax Exemption Failure Events

idstring

required

Event unique identifier

Format: uuid

created_atstring

required

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

Format: date-time

typestring

required

Type of the tax exemption failure events webhook.

TAX_EXEMPTION.CREATION_FAILED - Tax exemption creation failed.
TAX_EXEMPTION.UPDATE_FAILED - Tax exemption update failed.
TAX_EXEMPTION.DELETION_FAILED - Tax exemption deletion failed.

Enum: TAX_EXEMPTION.CREATION_FAILED
TAX_EXEMPTION.UPDATE_FAILED
TAX_EXEMPTION.DELETION_FAILED

objectobject (Webhook - Tax exemption - Created - Tax exemption)

required

idstring

required

Tax Exemption Unique Identifier

Format: uuid

created_atstring

required

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

Format: date-time

updated_atstring

required

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

Format: date-time

reasonstring

required

Reason for the failure of the tax exemption request.

statusstring

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.

Enum: NEW
ACTIVE
EXPIRED
CANCELLED

user_idsarray

required

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

User unique identifier.

Format: uuid

webhook_idstring

required

Webhook unique identifier.

Format: uuid

Responses

Request examples

{
  "id": "2ce641a1-e89c-43be-b8d8-981d4aac5bd5",
  "created_at": "2024-01-01T10:34:43Z",
  "type": "TAX_EXEMPTION.CREATION_FAILED",
  "object": {
    "id": "f1a57a04-1a89-4dab-ae3a-ff9b2a9377c1",
    "created_at": "2024-01-01T10:33:43Z",
    "updated_at": "2024-01-01T10:33:43Z",
    "reason": "Missing TIN",
    "status": "CANCELLED",
    "user_ids": [
      "70821d79-366f-4873-804b-14857d690496"
    ]
  },
  "webhook_id": "606e3c01-c9cf-4073-900e-718bfc521953"
}

Response examples

Request has been processed successfully.

Empty response

Was this page helpful?