Frequently Asked Questions

vatnode is an EU VAT number validation API. You send a VAT ID, and vatnode checks it in real time against the official EU VIES system, enriches it with national registry data where available, and returns a clean JSON response with the validity result, company details, VAT rates for that country, and a timestamped audit reference. It's built for developers adding VAT validation to invoicing, checkout, or supplier-onboarding flows.

Create a free account, open the dashboard, and you'll have a working API key immediately — no credit card. Every new account starts with a test key so you can build against deterministic fixtures before touching live data. When you're ready for real checks, create a live key in the dashboard and call GET /v1/vat/:vatId with it.

Test keys only accept XX-prefixed VAT numbers (e.g. XX0000001) and return fixed, predictable fixture responses — no VIES call, no database write, and nothing counts against your quota. Live keys validate real VAT IDs against VIES and count toward your monthly quota. Use test keys to build and verify your integration, then switch to a live key in production.

Pass your API key as a Bearer token in the Authorization header. You manage keys — creating, naming, and revoking them — entirely from the dashboard. Never expose a live key in client-side code; keep it server-side.

No. The Free plan gives you 100 live validations per month with no card required, which is enough to fully build and test an integration before deciding on a paid plan.

When you sell goods B2B to a customer in another EU country, you can generally zero-rate the supply as an intra-Community supply — but only if the customer has a valid EU VAT number (validated in VIES) at the time of supply, you report it on your EC Sales List, and you can evidence both the check and that the goods actually crossed the border. For cross-border B2B services the mechanism is different: the supply is outside your country's VAT and the customer accounts for VAT under the reverse charge. If the conditions aren't met or you can't evidence them, the tax authority can deny the zero-rating and assess the VAT against you.

vatnode queries the official VIES database in real time, so accuracy is as good as the EU system itself: when VIES says "valid", the number was registered and active at the exact moment of the check. Some member states update their registrations closer to real time than others, so a very recent change may take a day or two to appear. Valid results are cached for 15 minutes for speed; for absolute certainty on a high-value transaction you can force a fresh VIES check with force=true.

VIES validates VAT numbers regardless of the legal form behind them — a VAT-registered sole trader's number validates the same way a company's does. One caveat that applies to both: VIES only shows numbers a member state has enabled for intra-EU transactions, so a purely domestic VAT registration may not appear. Whether a name and address come back depends on that country's data policy, not the business type.

It's the EU Commission's requestIdentifier for a specific check — the official EU-side reference some tax authorities expect as audit evidence. It's opt-in: vatnode returns it only when you supply your own EU VAT number as the requester (in the dashboard or via the requesterVat query param), because the identifier is tied to your VAT, not ours. It isn't unique to vatnode — other providers return it too — but you don't need it for everyday validation; the checkId and verifiedAt on every response already give you a timestamped record.

Yes. On top of the VIES verdict, vatnode adds a national-registry layer for several countries — which keeps returning results for those countries during VIES country-level outages, and can enrich the response with data VIES doesn't carry (registration date, legal form, industry description). Every response also includes full VAT metadata for the company's country — the local tax name, abbreviation, and all rate tiers — so you can label and rate an invoice correctly in a single call.

Live validation covers all 27 EU member states plus Northern Ireland (XI), all through VIES. (Note: vatnode follows the VIES convention of EL for Greece, not the ISO GR.) VAT-rate and format reference data covers a wider set of European countries, but number validation is EU-27 + XI only.

No — those are outside VIES, so vatnode does not validate GB, NO, or CH VAT numbers. Their VAT rates are available in the rates reference data, but there's no live number validation. Northern Ireland businesses trading in goods with the EU use the XI prefix and are fully validated through VIES.

That's a data-policy decision by the individual country, not a vatnode limitation. Some member states — Germany and Spain among them — confirm validity through VIES but never return trader details. vatnode always tells you exactly what VIES returned, and for several countries fills gaps from national registries where their policy allows it.

VIES is shared infrastructure across 27 national tax authorities and has occasional outages, sometimes affecting just one country. When a check can't be completed and no fallback succeeds, vatnode returns HTTP 503 with the code VIES_UNAVAILABLE — which is very different from an "invalid" result. The right pattern is to treat it as a signal to retry later rather than to reject the customer; for several countries vatnode's national-registry fallback returns a result even while VIES is down.

A well-formed VAT number that simply isn't registered returns HTTP 200 with valid: false — that's a normal answer, not an error. Errors are separate: INVALID_FORMAT (400) means the string isn't a valid VAT ID shape and never reached VIES; VIES_UNAVAILABLE (503) means the EU system was down; RATE_LIMITED (429) means you hit your monthly quota; INVALID_REQUESTER (422) means the requester VAT you configured is itself invalid. Every error response includes a machine-readable code and a requestId.

vatnode does not publish a numeric uptime SLA on its self-serve plans. Reliability comes from caching plus the national-registry fallback that keeps answers flowing across VIES outages. Enterprise customers can request a custom SLA as part of an agreement.

There's no per-second or per-minute rate limit today — the only limit is your monthly quota. Each live response includes RateLimit-* headers showing your limit, remaining count, and reset time so you can track headroom from your own logs.

Free (100 requests/month, no card), Starter at €19/month (1,000 requests), Pro at €49/month (10,000 requests), and Enterprise (custom limits, on request). Paid plans also unlock VAT-monitoring subscriptions and webhooks; the Free plan is validation-only. Billing is monthly, with no annual commitment.

Only calls to the validation endpoint (/v1/vat/:vatId) count against your monthly quota. The VAT rates endpoint (/v1/rates) and dashboard/account API calls are free and don't count. A malformed request rejected as INVALID_FORMAT, a VIES_UNAVAILABLE outage, and a quota-exceeded 429 are not charged — only requests that return an actual valid/invalid determination consume a quota slot.

Yes — every validation call counts, whether the answer came fresh from VIES or from vatnode's 15-minute cache; you get the same validated data either way (cached responses are just faster). If you're validating the same counterparties repeatedly, the most effective saving is to cache successful results in your own application and skip re-checking a number you validated within the last day.

On the Free plan, once you've used your 100 monthly requests, further validation calls return HTTP 429 (RATE_LIMITED) until your quota resets at the next monthly period. There's no overage on Free — to keep validating in the same period, upgrade to a paid plan, which takes effect immediately.

Paid plans don't hard-stop at the included quota — they keep processing, and requests beyond the quota are billed as pay-as-you-go overage (€0.025/request on Starter, €0.015/request on Pro). There's no overage cap, so your service isn't interrupted mid-month. The dashboard shows live usage and we email you at 80% of your plan quota so there are no surprises.

Yes, from the dashboard at any time. Upgrades take effect immediately; downgrades take effect at the start of your next billing cycle. Unused requests don't roll over.

Payments are handled by Mollie (major cards and SEPA Direct Debit; Enterprise can pay by invoice). vatnode issues its own sequential, gap-free invoices for every charge, available as PDFs in the dashboard. Listed prices exclude VAT. Business customers in another EU country can enter a valid VAT number at checkout to be invoiced under the reverse charge at 0%; customers in Finland are charged Finnish VAT.

You can cancel any time from the dashboard; a paid subscription stays active until the end of the period you've paid for, and a free account can be closed at any point. Subscription fees are generally non-refundable because vatnode is a digital service that starts immediately, but we issue goodwill refunds for billing errors, documented sustained outages on our side, and an early-trial window within 7 days of a first paid charge. The full policy is at /legal/refunds.

Yes. The standard GDPR Article 28 DPA is at /legal/dpa and is automatically incorporated into your agreement on any paid plan — no signature needed. Enterprise customers who need a countersigned copy can request one at [email protected]. Our subprocessors are listed at /legal/subprocessors.

vatnode is operated by TMI Iurii Rogulia, based in Finland, and is hosted in the EU. VAT checks are processed against the EU VIES system and, where used, national tax-authority and company-registry APIs.

Your own checks are recorded as your audit history — the result, company details, and verifiedAt timestamp — accessible via the API and dashboard for as long as your account is active, so you can prove a check happened at the time of a transaction. vatnode doesn't build an archive of third parties' checks beyond your own audit records. You can export or delete your records; details and retention are covered in the privacy policy and DPA.

Yes. Every response includes a checkId and a verifiedAt timestamp recording exactly when the validation ran — store the checkId alongside the VAT number on your invoice record and you have a persistent, timestamped reference to the exact check. For stronger evidence, set your own EU VAT as the requester and vatnode also returns the VIES consultation number (see the validation section above).

Yes — vatnode publishes an official MCP server (vatnode-mcp) that works with any MCP-compatible client such as Claude, Cursor, or ChatGPT. Rate lookups and offline format checks run locally with no key; only live VIES validation needs a vatnode API key. The server runs on your machine via npx, so your key goes directly to the vatnode API with no third-party proxy.

On paid plans you can add a VAT number as a monitoring subscription, and vatnode re-validates it on a schedule (Pro checks daily; Starter less frequently) and fires a webhook when something changes — for example the number becoming invalid or company details changing. This is useful for ongoing supplier or customer relationships rather than one-off checks. Monitoring and webhooks aren't available on the Free plan.

Email [email protected] from the address on your account. Include your requestId (returned on every API response) when reporting an issue with a specific call — it lets us find the exact request in the logs quickly.