Entity VAT IDs

Overview

A VAT ID (Value Added Tax Identification Number) is an identification number used for tax purposes, specifically for value-added tax. It is assigned to entities 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.

Roles and permissions

To use the /entities/{entity_id}/vat_ids* endpoints with an entity user token, this entity user must have a role with the entity_vat_ids permission.

If using a partner-level token, no special permissions are needed.

Supported VAT ID types

Currently, Monite supports the following VAT ID types:

Add a VAT ID to an entity

To add a VAT ID to an entity, call POST /entities/{entity_id}/vat_ids and specify the VAT ID type, value, and the country where this VAT ID is registered:

1
curl -X POST 'https://api.sandbox.monite.com/v1/entities/{entity_id}/vat_ids' \
2
     -H 'X-Monite-Version: 2024-01-31' \
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": "123456789"
10
     }'

The successful response contains a unique id assigned to this VAT ID object, along with other information:

1
{
2
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
3
  "country": "DE",
4
  "type": "eu_vat",
5
  "value": "123456789",
6
  "entity_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
7
}

Note down the id of this VAT ID object - you will need to specify it later in the entity_vat_id_id field when creating invoices:

1
{
2
  "type": "invoice",
3
  "line_items": [
4
    ...
5
  ],
6
  ...
7
  "entity_vat_id_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
8
}

Multiple VAT IDs

An entity that sells globally may be registered for VAT in multiple jurisdictions. In this case, make sure to add all VAT IDs that this entity has.

Example: UK entities that trade under the Northern Ireland Protocol

UK entities that ship goods from Northern Ireland to the European Union fall under the Northern Ireland (NI) Protocol. Among other things, the NI Protocol requires that invoices for such sales display the seller VAT ID with the “XI” prefix instead of “GB”.

To account for this, UK entities need to add two VAT IDs:

• one with type="eu_vat" - to be used for sales invoices that fall under the NI Protocol;
• another one with type="gb_vat" - to be used for all other sales invoices.

Below are the payload examples to be used with POST /entities/{entity_id}/vat_ids. Note that the VAT ID country (“GB”) and value (VAT number) are the same in both examples. The only difference is the type, which determines the VAT ID prefix that will appear on PDF invoices.

1
{
2
  "country": "GB",
3
  "type": "eu_vat",
4
  "value": "123456789"
5
}

1
{
2
  "country": "GB",
3
  "type": "gb_vat",
4
  "value": "123456789"
5
}

Make sure to specify the correct VAT ID (of type gb_vat or eu_vat) for each invoice or other document created by the entity:

1
{
2
  "type": "invoice",
3
  ...
4
  "entity_vat_id_id": "<UUID of the 'gb_vat' or 'eu_vat' VAT ID object>"
5
}

List all VAT IDs

To get a list of all VAT IDs associated with an entity, call GET /entities/{entity_id}/vat_ids.

Retrieve a VAT ID

To get the details of a specific VAT ID associated with an entity, call GET /entities/{entity_id}/vat_ids/{vat_id}.

Edit a VAT ID

To update an existing VAT ID of an entity, call PATCH /entities/{entity_id}/vat_ids/{vat_id}.

Delete a VAT ID

To delete an existing VAT ID from the list of VAT IDs associated with the specified entity, call DELETE /entities/{entity_id}/vat_ids/{vat_id}.