HomeGuidesRecipesAPI ExplorerForumSupport
Partner Portal
Partner Portal

Manage VAT IDs

Learn how to manage the entities' 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:

CountryTypeDescriptionExample
Australiaau_abnAustralian Business Number (AU ABN)51824753556
Australiaau_arnAustralian Taxation Office Reference Number518247535567
Austriaeu_vatEuropean VAT numberATU12345678
Belgiumeu_vatEuropean VAT numberBE0123456789
Brazilbr_cnpjBrazilian CNPJ number28.271.211/0001-88
Brazilbr_cpfBrazilian CPF number137.609.391-04
Bulgariabg_uicBulgaria Unified Identification Code123456789
Bulgariaeu_vatEuropean VAT numberBG0123456789
Canadaca_bnCanadian BN123456789
Canadaca_gst_hstCanadian GST/HST number123456789RT0002
Canadaca_pst_bcCanadian PST number (British Columbia)PST-1234-5678
Canadaca_pst_mbCanadian PST number (Manitoba)123456-7
Canadaca_pst_skCanadian PST number (Saskatchewan)1234567
Canadaca_qstCanadian QST number (Québec)1234567890TQ1234
Chilecl_tinChilean TIN12.345.678-K
Croatiaeu_vatEuropean VAT numberHR12345678912
Cypruseu_vatEuropean VAT numberCY12345678Z
Czech Republiceu_vatEuropean VAT numberCZ1234567890
Denmarkeu_vatEuropean VAT numberDK12345678
Estoniaeu_vatEuropean VAT numberEE123456789
European Unioneu_oss_vatEuropean One Stop Shop VAT number for non-Union schemeEU123456789
Finlandeu_vatEuropean VAT numberFI12345678
Franceeu_vatEuropean VAT numberFRAB123456789
Georgiage_vatGeorgian VAT123456789
Germanyeu_vatEuropean VAT numberDE123456789
Greeceeu_vatEuropean VAT numberEL123456789
Hong Konghk_brHong Kong BR number12345678
Hungaryhu_tinHungary tax number (adószám)12345678-1-23
Hungaryeu_vatEuropean VAT numberHU12345678912
Icelandis_vatIcelandic VAT123456
Indiain_gstIndian GST number12ABCDE3456FGZH
Indonesiaid_npwpIndonesian NPWP number12.345.678.9-012.345
Irelandeu_vatEuropean VAT numberIE1234567AB
Israelil_vatIsrael VAT12345
Italyeu_vatEuropean VAT numberIT12345678912
Japanjp_cnJapanese Corporate Number (Hōjin Bangō)1234567891234
Japanjp_rnJapanese Registered Foreign Businesses' Registration Number (Tōroku Kokugai Jigyōsha no Tōroku Bangō)12345
Japanjp_trnJapanese Tax Registration Number (Tōroku Bangō)T1234567891234
Kenyake_pinKenya Revenue Authority Personal Identification NumberP000111111A
Latviaeu_vatEuropean VAT numberLV12345678912
Liechtensteinli_uidLiechtensteinian UID numberCHE123456789
Lithuaniaeu_vatEuropean VAT numberLT123456789123
Luxembourgeu_vatEuropean VAT numberLU12345678
Malaysiamy_frpMalaysian FRP number12345678
Malaysiamy_itnMalaysian ITNC 1234567890
Malaysiamy_sstMalaysian SST numberA12-3456-78912345
Maltaeu_vatEuropean VAT numberMT12345678
Mexicomx_rfcMexican RFC numberABC010203AB9
Netherlandseu_vatEuropean VAT numberNL123456789B12
New Zealandnz_gstNew Zealand GST number123456789
Norwayno_vatNorwegian VAT number123456789MVA
Polandeu_vatEuropean VAT numberPL1234567890
Portugaleu_vatEuropean VAT numberPT123456789
Romaniaeu_vatEuropean VAT numberRO1234567891
Russiaru_innRussian INN1234567891
Russiaru_kppRussian KPP123456789
Saudi Arabiasa_vatSaudi Arabia VAT123456789012345
Singaporesg_gstSingaporean GSTM12345678X
Singaporesg_uenSingaporean UEN123456789F
Slovakiaeu_vatEuropean VAT numberSK1234567891
Sloveniasi_tinSlovenia tax number (davčna številka)12345678
Sloveniaeu_vatEuropean VAT numberSI12345678
South Africaza_vatSouth African VAT number4123456789
South Koreakr_brnKorean BRN123-45-67890
Spaines_cifSpanish NIF number (previously Spanish CIF number)A12345678
Spaineu_vatEuropean VAT numberESA1234567Z
Swedeneu_vatEuropean VAT numberSE123456789123
Switzerlandch_vatSwitzerland VAT numberCHE-123.456.789 MWST
Taiwantw_vatTaiwanese VAT12345678
Thailandth_vatThai VAT1234567891234
Ukraineua_vatUkrainian VAT123456789
United Arab Emiratesae_trnUnited Arab Emirates TRN123456789012345
United Kingdomgb_vatUnited Kingdom VAT numberGB123456789
United Kingdomeu_vatNorthern Ireland VAT number. Used for transactions that fall under the Northern Ireland Protocol. See below for details.XI123456789
United Statesus_einFederal Tax Identification Number or United States EIN12-3456789

📘

Need another VAT ID type?

To request additional VAT ID types, send us an email to [email protected].

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:

curl -X POST 'https://api.sandbox.monite.com/v1/entities/{entity_id}/vat_ids' \
     -H 'X-Monite-Version: 2023-09-01' \
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
     -H 'Authorization: Bearer ACCESS_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{
       "country": "DE",
       "type": "eu_vat",
       "value": "123456789"
     }'

📘

When creating a VAT ID, entities in the Canary Islands (IC) and autonomous Spanish cities—Ceuta and Melilla (EA)— can provide es_cif for the type field. However, their country field must adhere to the ISO 3166 country code standard for the respective regions.

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

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

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:

{
  "type": "invoice",
  "line_items": [
    ...
  ],
  ...
  "entity_vat_id_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"  <-------
}

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.

VAT ID payload for NI ProtocolVAT ID payload for all other sales
{
"country": "GB",
"type": "eu_vat",
"value": "123456789"
}
{
"country": "GB",
"type": "gb_vat",
"value": "123456789"
}

📘

Do not include the "XI" or "GB" prefix in the value. Monite will add these prefixes to VAT IDs automatically when generating PDF invoices.

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:

{
  "type": "invoice",
  ...
  "entity_vat_id_id": "<UUID of the 'gb_vat' or 'eu_vat' VAT ID object>"  <-------
}

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}.