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 follow the quickstart guide to 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. The test mode guide lists every fixture and what it returns. 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 — same endpoint, same response shape, just a different key.

Pass your API key as a Bearer token in the Authorization header: Authorization: Bearer vat_live_.... The authentication guide has full request examples and the error responses for a missing or revoked key. 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. See pricing for what each paid tier adds if you outgrow it.

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 — see the EU VAT for B2B SaaS guide for how that plays out for subscription businesses specifically. 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 — the cacheHit field on every response tells you whether an answer was fresh or served from cache. If you've set your own EU VAT as the requester in dashboard Settings, caching is bypassed automatically so every check gets a fresh VIES lookup; see the validation endpoint reference for the exact behavior.

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 — the country coverage reference lists exactly which fields each country returns.

It's the EU Commission's requestIdentifier for a specific check — the official EU-side reference some tax authorities (notably France and Germany) expect as audit evidence, alongside an invoice that applied reverse charge. It's opt-in: vatnode returns it only once you set your own EU VAT number as the requester in dashboard Settings, because the identifier is issued against your VAT, not vatnode's — a check run under vatnode's own VAT would be worthless as evidence for your invoice. You don't strictly need it for everyday, non-audit validation. Without a requester configured, every response still includes a checkId and a verifiedAt timestamp, but those are vatnode's own internal reference for the call — useful for looking a specific check up with support, not evidence by themselves. See the VAT audit trail guide for the full picture, including how retention requirements vary by country.

Yes. On top of the VIES verdict, vatnode adds a national-registry layer for several countries — see the country coverage reference for exactly which ones — 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, the same data as the VAT rates endpoint — 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.) The coverage reference breaks this down country by country — which ones return company details, registration date, legal form, industry, and a national registry identifier on top of the VIES verdict.

VAT-rate and format reference data covers a wider set of European countries, but number validation itself is EU-27 + XI only — see the next question for what's outside that scope.

No — those are outside VIES, so vatnode does not validate GB, NO, or CH VAT numbers. Their VAT rates and number formats are available in the rates reference data, but there's no live number validation for them, and none is planned since it would need each country's own registry rather than VIES. Northern Ireland businesses trading in goods with the EU use the XI prefix and are fully validated through VIES — full country-by-country detail is in the coverage reference.

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 — the coverage reference lists which countries get that enrichment and what fields it adds.

VIES is shared infrastructure across 27 national tax authorities and has occasional outages, sometimes affecting just one country. If no requester VAT is configured in dashboard Settings, vatnode first tries the national-registry fallback for supported countries, so many checks still get an answer while VIES is down. When a check can't be completed and no fallback succeeds — or a requester is set, which deliberately skips the fallback to preserve the consultation number — vatnode returns HTTP 503 with the code VIES_UNAVAILABLE, which is very different from an "invalid" result. The error reference documents this and every other error code in full; live status shows current VIES and national-fallback health per country. The right pattern is to treat VIES_UNAVAILABLE as a signal to retry later rather than to reject the customer.

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 in dashboard Settings is itself invalid in VIES. Every error response includes a machine-readable code and a requestId. The error reference has the full response shape, every HTTP status code vatnode returns, and how to handle each one.

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. The status page shows live API/database/cache health and 30-day VIES uptime by country, refreshed continuously. 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-Limit, RateLimit-Remaining, and RateLimit-Reset headers, plus a Vatnode-Quota-Warning nudge once you're near your limit, so you can track headroom from your own logs. Full header semantics and examples are in the rate limits reference.

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) — see the full breakdown on the pricing page. Paid plans also include VAT-monitoring subscriptions and webhooks; the Free plan is validation-only. Starter and Pro can be billed monthly or annually — annual billing works out to a reduced monthly rate (Starter €16/mo, Pro €41/mo), billed as €192/year and €492/year respectively, with your quota still resetting every month.

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. Every response carries RateLimit-* headers so you can track exactly how many requests you have left without checking the dashboard, and the pricing page lists the monthly quota for each plan.

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. You can watch your remaining quota move in real time via the RateLimit-* response headers.

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 — the RateLimit-* response headers tell you exactly where you stand before you hit the wall. 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; see the pricing page for the full plan breakdown). 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 — the same threshold also shows up as a RateLimit-* response header on every call. Annual billing works the same way: your quota resets every month, and if you go over in a given month that month's overage is billed then — pay-as-you-go, uncapped — on top of your annual charge.

Yes, from the dashboard at any time — see the pricing page for the full plan and quota breakdown before you switch. 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 on the pricing page 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%; EU consumers and businesses without a valid VAT ID — Finnish customers included — are charged Finnish VAT, since vatnode applies its home-country rate rather than each buyer's local rate. Customers outside the EU aren't charged 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. All infrastructure — database, API, and web hosting — runs on servers in Frankfurt, Germany, so your data stays in the EU end to end. VAT checks are sent to the EU VIES system and, for some countries, national tax-authority or company-registry APIs; requester VAT numbers (when you set one) go to VIES only. The full subprocessor list, with entity names and locations, is at /legal/subprocessors; data-protection terms are in the privacy policy and DPA.

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; a check you run isn't visible to the business you checked or to anyone else. You can request an export or deletion at any time; full retention terms — including automatic anonymisation after 5 years and deletion within 30 days of closing your account — are in the privacy policy and DPA.

Only the VIES consultation number counts as proof. Set your own EU VAT as the requester in dashboard Settings and every live check returns it — an EU Commission-issued reference that tax authorities recognize (see the validation section above). checkId is vatnode's internal identifier for the call, mainly useful for looking a specific check up with support — it isn't evidence by itself. verifiedAt is just an informational timestamp of when the check ran. Retention requirements vary by country, so confirm yours with a tax advisor. See the audit-trail guide for what to store and why.

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.

Yes — on Starter and above you can add a VAT number as a monitoring subscription, and vatnode re-validates it daily 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. Starter includes 25 monitored VAT numbers and 3 webhook endpoints (see pricing for other plans); 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.