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.

tax_exemption_detailsOne Of

required

Must match one of

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.

tax_exemption_detailsOne Of

required

Must match one of

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

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

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?