Counterpart VAT IDs

Overview

A VAT ID (Value Added Tax Identification Number) is a unique government-issued identification number used for tax purposes, specifically for value-added tax. It is assigned to counterparts and helps authorities track and manage tax-related transactions.

VAT ID names and formats vary from country to country. For example, in the European Union it is referred to as “VAT identification number” or VATIN. Common names in other countries include Business Number (BN), Good and Services Tax number, and sales tax numbers.

Businesses (or counterparts) can have one, multiple, or no VAT IDs depending on the country and regulatory requirements. For example, some countries do not require VAT registration for small businesses with a turnover below a certain threshold. Whereas businesses selling globally are often registered for VAT in multiple jurisdictions and thus have multiple VAT IDs.

Check if VAT ID is required for counterpart

See Counterpart tax ID and VAT ID.

Supported VAT ID types

Currently, Monite supports the following VAT ID types:

Add new VAT ID

To associate a new VAT ID with a specific counterpart, call POST /counterparts/{counterpart_id}/vat_ids, passing the VAT ID type and value in the request body:

1
curl -X POST 'https://api.sandbox.monite.com/v1/counterparts/411dcb...289b3/vat_ids' \
2
     -H 'X-Monite-Version: 2024-05-25' \
3
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
4
     -H 'Authorization: Bearer ACCESS_TOKEN' \
5
     -H 'Content-Type: application/json' \
6
     -d '{
7
       "country": "DE",
8
       "type": "eu_vat",
9
       "value": "DE12345678"
10
     }'

The successful response contains the information about the newly added VAT ID:

1
{
2
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
3
  "counterpart_id": "411dcb68-dad8-46c2-92b9-f6ae445289b3",
4
  "country": "DE",
5
  "type": "eu_vat",
6
  "value": "DE12345678"
7
}

List all VAT IDs

To get all VAT IDs of a specific counterpart, send a GET request to the /counterparts/{counterpart_id}/vat_ids endpoint as shown:

1
curl -X GET 'https://api.sandbox.monite.com/v1/counterparts/411dcb...289b3/vat_ids' \
2
     -H 'X-Monite-Version: 2024-05-25' \
3
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
4
     -H 'Authorization: Bearer ACCESS_TOKEN'

The successful response contains a list of VAT IDs of the specified counterpart:

1
{
2
  "data": [
3
    {
4
      "country": "DE",
5
      "type": "eu_vat",
6
      "value": "DE12345678",
7
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
8
      "counterpart_id": "411dcb68-dad8-46c2-92b9-f6ae445289b3"
9
    }
10
  ]
11
}

Retrieve a VAT ID

To retrieve a specific VAT ID belonging to a counterpart, send a GET request to the /counterparts/{counterpart_id}/vat_ids/{id} endpoint as shown:

1
curl -X GET 'https://api.sandbox.monite.com/v1/counterparts/411dcb...289b3/vat_ids/3fa85f64...2c963f66afa6' \
2
     -H 'X-Monite-Version: 2024-05-25' \
3
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
4
     -H 'Authorization: Bearer ACCESS_TOKEN'

The successful response returns an object containing details of the counterpart’s VAT ID requested.

1
{
2
  "country": "AF",
3
  "type": "eu_vat",
4
  "value": "123456789",
5
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
6
  "counterpart_id": "411dcb68-dad8-46c2-92b9-f6ae445289b3"
7
}

Edit a VAT ID

To edit an existing VAT ID of a specific counterpart, send a PATCH request to the /counterparts/{counterpart_id}/vat_ids/{id} endpoint. You can update the VAT ID type, value, or country.

1
curl -X PATCH 'https://api.sandbox.monite.com/v1/counterparts/411dcb...289b3/vat_ids/3fa85f64...2c963f66afa6' \
2
     -H 'X-Monite-Version: 2024-05-25' \
3
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
4
     -H 'Authorization: Bearer ACCESS_TOKEN' \
5
     -H 'Content-Type: application/json' \
6
     -d '{
7
       "country": "AF",
8
       "type": "eu_vat",
9
       "value": "AF125678"
10
     }'

The successful response returns an object containing details of the updated VAT ID.

1
{
2
  "country": "AF",
3
  "type": "eu_vat",
4
  "value": "123456789",
5
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
6
  "counterpart_id": "411dcb68-dad8-46c2-92b9-f6ae445289b3"
7
}

Delete a VAT ID

To delete an existing VAT ID from the list of VAT IDs associated with a specific counterpart, send a DELETE request to the /counterparts/{counterpart_id}/vat_ids/{id} endpoint as shown:

1
curl -X DELETE 'https://api.sandbox.monite.com/v1/counterparts/411dcb...289b3/vat_ids/3fa85f64...2c963f66afa6' \
2
     -H 'X-Monite-Version: 2024-05-25' \
3
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
4
     -H 'Authorization: Bearer ACCESS_TOKEN'