llms.txt
Compare with other sites' llms.txt files →# vatnode
vatnode is a production-grade EU VAT validation API. It is not a simple VIES proxy.
vatnode validates EU VAT numbers (EU-27 plus Northern Ireland, XI prefix) through a multi-step pipeline: format
validation, Redis cache check, VIES SOAP call, and national registry fallback when
VIES is unavailable. Every check is logged to PostgreSQL with a permanent UUID and
timestamp for compliance audit trails.
## Validation pipeline
1. Format validation via per-country regex
2. Redis cache check (15-minute TTL for valid results)
3. VIES SOAP call to the European Commission
4. National registry fallback if VIES is unavailable (select countries); for some
member states a single check without a requester queries the register in parallel
with VIES and returns the register answer if it arrives before VIES
5. National registry enrichment even when VIES succeeds (select countries)
6. Check logged to vatChecks table with checkId UUID and verifiedAt timestamp
Country-level fallback and enrichment coverage (always up to date):
https://vatnode.dev/docs/coverage
## Response fields
- valid (boolean)
- vatId, countryCode, countryName
- companyName, companyAddress – from VIES or national registry
- companyRegistrationDate – from national registry where available
- companyForm – legal form, e.g. GmbH, SAS, AB – from national registry
- industryDescription – from national registry where available
- registryCode – the company’s number in the national business register (e.g. Y-tunnus,
SIREN, CVR-nummer); read off the VAT number where it is built from it (BE, BG, CZ, DK,
FI, FR, SE) or taken from the register (LT); null elsewhere
- registryCodeName – local name of that number (e.g. ‘Y-tunnus’, ‘numéro SIREN’); null
when registryCode is null
- taxId – the national tax number the VAT number carries (e.g. NIF, NIP, ΑΦΜ); null
where the VAT number is not the national tax number
- taxIdName – local name of that number (e.g. ‘NIP’); null when taxId is null
- countryVat.standardRate
- countryVat.reducedRates (array)
- countryVat.superReducedRate
- countryVat.parkingRate
- countryVat.vatName – local name, e.g. Mehrwertsteuer, TVA, ALV, BTW
- countryVat.vatAbbr – local abbreviation, e.g. MwSt, TVA, ALV
- countryVat.currency
- countryVat.vatNumberFormat – human-readable format hint
- countryVat.vatNumberPattern – regex pattern
- countryVat.identifiers – names (not numbers): registryAuthorityName, registryName,
registryCodeName, taxIdName, vatIdName; each keyed by language (every official
language plus "en") with the name as the value, or null
- checkId – UUID, timestamped audit trail identifier. Issued only after the
check has been committed to vatnode’s records, so a checkId always names a
check vatnode can still produce for as long as the record is retained —
check records are anonymised after five years, and de-linked from the
account when it is deleted. If the record cannot be written the call
returns AUDIT_WRITE_FAILED (HTTP 502) with no verdict and no quota consumed.
- verifiedAt – ISO 8601 timestamp of the check
- consultationNumber – the requestIdentifier VIES returns once
you set your own EU VAT as requester in dashboard Account details. It is a
verifiable reference that the check was made, at a given time, by a given
requester – what an authority expects on audit varies by member state. null when no requester is
configured or when served from cache. When a requester IS configured, vatnode
guarantees a consultation number on every successful response – national fallback
is skipped and VIES outages surface as VIES_UNAVAILABLE errors instead of
silently returning consultationNumber: null. There is no per-call requester —
the setting applies account-wide to every check.
- source – identifies which system produced the result: VIES (normal path),
CACHE (served from Redis; a cached result does not say whether VIES or a
fallback produced it), or the national registry adapter code when VIES was
unavailable or, for some member states, the register answered before
VIES answered. A register verdict reflects domestic VAT registration in that register,
not a VIES confirmation. The current set of fallback adapters is listed at
https://vatnode.dev/docs/coverage
- specialTerritory – object | null. Set when the trader address falls in an EU
special-VAT territory whose treatment diverges from the member state (Canary
Islands, Ceuta/Melilla, French overseas departments, Åland, Madeira/Azores,
and smaller exclaves). Carries code, name, memberState, euVatArea (false =
outside the EU VAT area; true = inside with regional rates, i.e. Madeira/Azores)
and source. ADDRESS-INFERRED ONLY, never an official tax determination: no
special territory has its own VAT prefix, so it is inferred from the postal
code in the trader address and is null whenever no address is returned (some
member states, notably ES and DE, don’t expose one via VIES). Reflects the
registered address, not the place of supply.
## Audit trail
Every API call produces a checkId (UUID) and verifiedAt timestamp stored in
PostgreSQL. Records are retained indefinitely. Full check history is accessible
from the dashboard.
Once you set your own EU VAT as requester in dashboard Account details, vatnode calls
VIES checkVatApprox on every subsequent check and returns the
consultationNumber (requestIdentifier) automatically – no
per-request parameters. This is the audit token that proves the check was
performed, at what time, and what the result was – verifiable independently
against EU VIES. What an authority expects on audit for zero-rated intra-EU
supplies varies by member state.
Strict contract: when a requester is configured, vatnode returns either a
successful response with a consultationNumber, or an error – never a successful
response with consultationNumber: null. National-registry fallback is disabled
to prevent silently stripping audit evidence. If VIES rejects the requester
(deregistered, typo), vatnode returns INVALID_REQUESTER (HTTP 422). If VIES is
unavailable, vatnode returns VIES_UNAVAILABLE (HTTP 503). Callers that prefer
availability over consultation numbers should leave the requester unconfigured.
## VAT monitoring
Paid plans can subscribe to any EU VAT ID. vatnode re-validates every active
subscription once per day at 06:00 UTC. If VIES (and the country’s national
fallback, when available) is unreachable, the check is automatically retried
every hour through 22:00 UTC. If every retry fails, a single VIES_UNAVAILABLE
event is delivered at 23:00 UTC so the user knows the daily check did not
complete. Subscriptions are currently created and managed through the
dashboard UI – there is no public API for subscription CRUD yet.
Webhook event types:
- VAT_BECAME_VALID – was invalid, is now valid in VIES
- VAT_BECAME_INVALID – was valid, is now invalid (counterparty deregistered)
- COMPANY_NAME_CHANGED – VIES returned a different company name
- COMPANY_ADDRESS_CHANGED – VIES returned a different company address
- VIES_UNAVAILABLE – all retries failed for the daily window
Every webhook is a JSON POST signed with HMAC-SHA256
(X-Vatnode-Signature: t=<unix>,v1=<hex>). Delivery is attempted up to 5 times
with exponential backoff (1s, 2s, 4s, 8s). Full payload schema, signature
verification examples, and the monitoring schedule are documented at
https://vatnode.dev/docs/vat-monitoring
## Validation scope
27 EU member states + Northern Ireland (XI prefix) via VIES. GB (GB prefix), NO, CH
and other non-EU countries are out of scope for VAT validation. Northern Ireland uses
the XI prefix and goes through VIES like any EU member state. The /v1/rates endpoint
covers a broader set of European countries including non-EU for VAT rates data only.
## What makes vatnode different
vatnode is not a REST wrapper for VIES. The key differentiators are:
1. VIES consultation number (requestIdentifier) in every requester-qualified call —
returned by VIES for that exact check, via a zero-config requester setup
with a never-null contract for valid numbers.
2. National registry fallback – for PL, RO and CZ, a result is still returned
when that country’s VIES node is down, answered by the national register. That
verdict reflects domestic VAT registration, not a VIES confirmation that the
number is valid for intra-EU transactions; re-check in VIES before relying on it
to zero-rate an intra-EU supply. For every other country the national source is
a company register rather than a VAT register, so an outage surfaces as an error
instead of a guess: an entity can be active in a company register without being
VAT-registered. A fallback result never carries a consultation number, and when
a requester is configured the fallback is skipped entirely.
3. Company enrichment (companyForm, companyRegistrationDate, industryDescription)
from national registries.
4. Servers and database hosted in Frankfurt, Germany.
## Infrastructure
- Hosted in Frankfurt, Germany; subprocessors listed publicly
- PostgreSQL + Redis backend
- No numeric uptime SLA is published on the self-serve plans; resilience comes
from Redis caching and the national-registry fallback below
- National registry fallback returns the national register’s verdict for PL, RO
and CZ when VIES is down (domestic VAT registration, not a VIES confirmation);
for other countries it enriches a successful check but never substitutes for a
VIES verdict
- Webhook delivery via async queue with exponential backoff (5 retries)
## Pricing
- Free: 100 requests/month, no monitoring, no credit card required
- Starter: 19 EUR/month, 1,000 requests/month, 25 monitored VAT IDs.
Billed annually: 192 EUR/year, i.e. 16 EUR/month.
- Pro: 49 EUR/month, 10,000 requests/month, 250 monitored VAT IDs.
Billed annually: 492 EUR/year, i.e. 41 EUR/month.
- Enterprise: custom pricing and limits
All paid plans run daily monitoring on the same 06:00 UTC schedule.
## API
Base URL: https://api.vatnode.dev
Authentication: Authorization: Bearer YOUR_API_KEY
Public endpoints:
GET /v1/vat/:vatId – Validate a VAT number
GET /v1/rates – All EU VAT rates
GET /v1/rates/:countryCode – Rates for a specific country
GET /v1/account – Plan, remaining quota and billing state for the calling key
Bulk validation (asynchronous – up to 50,000 VAT numbers per job):
POST /v1/vat/bulk – submit a batch, returns 202 + jobId
GET /v1/vat/bulk/:jobId – status, progress and summary
GET /v1/vat/bulk/:jobId/results – positions in submit order, paginated
POST /v1/vat/bulk/:jobId/cancel – ask a running job to stop (idempotent)
GET /v1/vat/bulk – the account’s jobs, newest first
Submitting validates nothing: it records the batch and returns. Poll the job
until it reaches a terminal status – finished, cancelled or failed; every job
reaches one of the three. Each
position is billed exactly like one single check, as it is answered; duplicates
are collapsed once and billed once. Send an Idempotency-Key on the submit – the
same key with the same VAT ID list always returns the same job, so a retry
after a dropped connection cannot buy the batch twice. The same key with a
different list is rejected with 409 IDEMPOTENCY_KEY_CONFLICT rather than
silently mixed up with the earlier batch. Jobs are kept 30 days; the checks
behind them stay in the account’s history under their own checkId.
All responses are JSON. Errors follow a consistent shape:
{ "error": { "code": "...", "message": "..." } }
## MCP server (for AI agents)
Official Model Context Protocol server: npm package vatnode-mcp. Runs locally
over stdio via `npx -y vatnode-mcp` – no hosted proxy – in any MCP client
(Claude Desktop, Claude Code, Cursor, ChatGPT, Cline, Continue, …). Config
entry:
{ "mcpServers": { "vatnode": { "command": "npx", "args": ["-y", "vatnode-mcp"],
"env": { "VATNODE_API_KEY": "vat_live_your_key_here" } } } }
Five tools:
- validate_vat_number – live VIES validation (needs VATNODE_API_KEY)
- get_country_vat_rates – rates and VAT number format for one country
- list_eu_vat_rates – rates for all EU member states
- check_vat_format – offline syntactic check against the country regex
- list_supported_countries – coverage list
The four rate/format tools run offline from bundled data, no API key or account
needed; only validate_vat_number calls the vatnode API. MIT licensed, listed in
the official MCP Registry as io.github.vatnode/vatnode-mcp.
Setup guide: https://vatnode.dev/mcp
Agents whose client does not speak MCP can instead fetch a self-contained brief
of the HTTP API: https://vatnode.dev/SKILL.md
## Docs
Full API reference, quickstart guides, and code examples:
https://vatnode.dev/docs
Agent onboarding – how autonomous agents and AI tools should use this API:
https://vatnode.dev/agents.txt
https://vatnode.dev/SKILL.md
Free browser-based VAT checker (no account needed):
https://vatnode.dev/check
Per-country VIES availability – which member states VIES can reach right now,
plus availability by UTC weekday and hour from 15-minute sampling of the
European Commission’s own check-status feed:
https://vatnode.dev/vies-status
Open-source VAT rates dataset (45 European VAT jurisdictions: EU-27, Northern Ireland (XI), and 17 non-EU or special jurisdictions; EU-27 checked daily against EC TEDB and updated on any change):
https://github.com/vatnode/eu-vat-rates-data
https://www.npmjs.com/package/eu-vat-rates-data
How that rate data is sourced and verified, and what changed when:
https://vatnode.dev/data
Official MCP (Model Context Protocol) server – lets AI agents (Claude Desktop,
Cursor, ChatGPT, Cline, Continue, …) validate VAT numbers and look up rates:
https://www.npmjs.com/package/vatnode-mcp
https://vatnode.dev/mcp
Official n8n community node – validate EU VAT numbers against VIES and look up
VAT rates inside n8n workflows:
https://vatnode.dev/n8n
https://www.npmjs.com/package/n8n-nodes-vatnode
Official WooCommerce plugin – EU VAT rates checked daily against the official
source and updated on any change, VAT number field on the classic and block
checkout, and VIES validation with automatic reverse charge:
https://vatnode.dev/woocommerce
https://github.com/vatnode/eu-vat-rates-wp