VAT number validation API for developers

Avatcado includes a built-in 25-day response cache with stale fallback. If VIES is temporarily unavailable for a specific country, the most recent cached result is returned with meta.cached: true, and if that entry is older than 25 days it also carries meta.stale: true so you can decide whether to accept it. The meta.source_status field tells you what happened upstream: "live" means the registry confirmed the result fresh, while "unavailable" means the member state was down and a stale cached result was served instead. Only when no cached data exists at all do you receive a 503 error with the machine-readable code upstream_member_state_unavailable and a docs_url explaining what to do, and that request is automatically refunded, so it never counts against your monthly quota. Never a silent failure, and no retry infrastructure for you to build. See our live VIES uptime data for current reliability metrics.

In our monitoring, fresh VIES lookups typically take 1-3 seconds depending on the member state; latency varies by country because each EU registry answers at its own speed. UK (HMRC) lookups are consistently fast. Cached responses return in milliseconds: results are cached for 25 days, so repeat validations of the same number skip the upstream registry entirely and arrive flagged with meta.cached: true. Caching also shields you from upstream limits such as the Swiss BFS UID Register's strict 20 requests per minute cap. Every response includes meta.request_duration_ms, the total processing time in milliseconds, so you can monitor performance in your own systems without extra instrumentation. If checkout latency matters, use async validation on Pro and Business plans: the endpoint returns 202 immediately and delivers the result to your webhook when validation completes, which keeps slow member states out of your critical path.

All 27 EU member states plus Northern Ireland via VIES (Northern Ireland uses the XI prefix), the United Kingdom via HMRC, Switzerland and Liechtenstein via the BFS UID Register (both countries share the Swiss registry), Norway via the Bronnoysund Register Centre, and Australia via the ABR (Australian Business Register). That is 32 countries backed by 5 official government registries behind one endpoint. Send any supported VAT or GST number to /v1/validate: Avatcado detects the country from the prefix, routes the lookup to the right registry, and returns the same snake_case JSON response shape for every country, so you write one integration instead of five. The /v1/rates endpoint covers VAT and GST rates for the same 32 countries. A number from an unsupported country returns a structured unsupported_country error instead of a false negative, so you can handle that case explicitly in your code.

Yes. GET /v1/rates returns current rates for all 32 supported countries in a single response: the standard rate plus reduced, super-reduced, and zero rates where a country has them, together with the country name, currency, and a per-country updated_at timestamp. GET /v1/rates/NL (or any supported country code) returns one country. Rates endpoints are free and unlimited on every tier, including Free, and never count against your monthly validation quota; only the standard per-minute burst limit applies. That makes them practical for high-frequency use, such as computing checkout prices on the fly or refreshing a pricing table on a daily schedule. Responses use the same { data, meta } envelope as validation responses, so your existing client code and error handling carry over unchanged. Deciding which rate applies to a specific product category remains your tax logic; the API reports the official current rates per country.

Yes. The free tier includes 500 validations per month, up to 2 API keys, and a burst limit of 20 requests per minute, with no credit card required. It uses the same API, the same response format, the same 25-day caching, and the same 32-country registry coverage as paid plans, so nothing about your integration changes when you upgrade. Test mode is included too: requests made with an avat_test_ key never reach the registries and never consume quota, so integration tests are effectively free and unmetered. VAT rate lookups via /v1/rates are also free and unlimited on every tier and do not count against the 500. When you need more volume, Pro offers 10,000 validations per month with 10 keys for EUR 39 per month (EUR 29 per month billed annually), and Business offers 50,000 per month with 100 keys for EUR 129 per month (EUR 99 per month billed annually).

Use a test-mode API key (prefixed avat_test_) and every request runs in test mode: nothing reaches VIES, HMRC, BFS, Bronnoysund, or ABR, nothing counts against your monthly quota, and every response carries meta.mode: "test" so you can tell environments apart. Magic VAT numbers trigger predictable scenarios: DE111111111 returns a valid company, DE000000000 returns valid: false, DE999999999 simulates a 503 upstream error, DE777777777 simulates a 429 rate limit response, and DE555555555 simulates the stale cache fallback. Magic numbers also exist for the UK, France, Switzerland, Liechtenstein, and Norway. Any other correctly formatted number returns a generic valid result, while malformed input still returns invalid_vat_format exactly as in live mode, so your error handling gets exercised too. The result is fast, deterministic integration tests with no flaky upstream dependencies. One exception: async endpoints require a live key. See the docs for the full list of magic numbers.

VIES is a SOAP-first service (the Commission also runs an official REST API) with inconsistent availability across member states, undocumented per-IP rate limits, no UK support, no batch endpoint, and no caching. When a member state is down you get a SOAP fault such as MS_UNAVAILABLE and are left to build your own retry and fallback logic. Avatcado wraps VIES, HMRC, the Swiss UID Register, the Norwegian Bronnoysund Register, and the Australian ABR in a modern REST API with JSON responses, a built-in 25-day cache with stale fallback for outages, documented per-tier rate limits, structured errors with machine-readable codes and a docs_url on every error, typed SDKs for TypeScript (@avatcado/node on npm) and Python (avatcado on PyPI), batch validation of up to 50 numbers per request, async validation with HMAC-SHA256 signed webhooks, and a deterministic test mode. You don't have to build and maintain that infrastructure yourself.

No. One API key, one endpoint. Avatcado detects the country from the number itself and routes automatically: EU prefixes and XI (Northern Ireland) go to VIES, GB goes to HMRC, CH and LI go to the Swiss BFS UID Register, NO goes to the Bronnoysund Register, and AU goes to the ABR. Input is normalized before routing, so lowercase letters, spaces, dots, and dashes are stripped, and common variants such as the Swiss CHE prefix or the Australian ABN prefix are rewritten to CH and AU for you. Every registry returns the same response shape, so there is no per-country parsing either. The only key distinction is mode: avat_test_ keys run in deterministic test mode while avat_live_ keys query real registries. If you want separate keys per service or environment anyway, you can create up to 2 on Free, 10 on Pro, and 100 on Business.

Yes. Since January 1, 2020, a valid customer VAT number has been a material requirement for applying the 0% VAT rate on intra-Community supplies within the EU, not just a formality. If you sell B2B cross-border and apply the reverse charge mechanism, you must verify your customer's VAT number. If the number turns out to be invalid on a transaction you zero-rated, you as the seller are liable for the VAT that should have been charged, plus potential interest and penalties. Reverse charge VAT validation should therefore be part of every B2B checkout flow rather than a cleanup job you run later. VAT numbers can also be deactivated or revoked at any time, so regular revalidation of stored numbers is recommended. Avatcado returns consultation numbers on every EU validation where you supply your own VAT number as requester, giving you timestamped proof of verification that tax authorities accept as evidence of due diligence.

A consultation number is a unique reference returned by VIES when you validate an EU VAT number while identifying yourself with your own VAT number. It proves that you checked the number on a specific date and received a specific result. That matters because a validation only tells you a number's status at the moment you ask; if a tax authority later questions a zero-rated intra-Community supply, the consultation number is your evidence that you verified the buyer's VAT status at the time of the transaction. To receive one from Avatcado, pass requester_vat_number alongside the number you are validating; the response then includes consultation_number, on all tiers, and HMRC provides an equivalent reference for UK checks. Consultation numbers are not available for Switzerland, Liechtenstein, Norway, or Australia. Store the consultation number, the full response, and the timestamp alongside each transaction so you are audit-ready without reconstructing anything later.

VATlayer only supports EU VAT validation: no UK coverage post-Brexit, no test mode, no typed SDKs, and no webhooks, although it is the cheapest EU-only option. VATsense covers more regions (including South Africa and Brazil) and ships SDKs in several languages, but offers no test mode, no batch validation, and no webhooks, and uses HTTP Basic Auth rather than bearer tokens. Avatcado validates across the EU, UK, Switzerland, Liechtenstein, Norway, and Australia with a single API. Every plan includes typed SDKs for TypeScript and Python, a deterministic test mode with magic VAT numbers, structured error codes with a docs_url on every error, and built-in 25-day caching with stale fallback when a registry goes down. Batch validation of up to 50 numbers per request and webhook-based async validation are available on Pro and Business plans. See the full API comparison guide, or the dedicated vatlayer and VATsense comparison pages, for details.

Yes. Avatcado is a standalone API, independent of your payment provider. Stripe validates tax IDs against government databases for three regions only (EU, UK, and Australia), and only within its billing flow, tied to Customer objects; for other countries, including Switzerland and Norway, Stripe performs a format check without confirming the number is real. Mollie and Adyen do not offer a customer VAT validation API at all. Avatcado works alongside any payment setup: validate at signup before the customer reaches checkout, revalidate stored numbers on a schedule, enrich CRM records with registry company names and addresses, or run compliance checks across your existing customer base. Because it is a plain REST API with typed SDKs for TypeScript and Python, you can call it from anywhere you need to verify a VAT or GST number, not just inside a payment flow. See the integration guides for Stripe, Mollie, and Adyen.

An ABN (Australian Business Number) is an 11-digit identifier issued to Australian businesses and held in the Australian Business Register (ABR). Avatcado validates ABNs against the ABR and returns the registered business name, ABN status, and whether the business is registered for GST. That last part matters: holding an ABN does not mean a business is GST-registered, because GST registration is separate and only becomes mandatory above AUD 75,000 annual turnover. Avatcado checks both. valid: true means the ABN exists and has an active GST registration; an existing ABN without GST registration returns valid: false with the company details still present, so you can distinguish the two cases in code. Send the number to the same /v1/validate endpoint you use for EU VAT numbers with the AU prefix, for example AU51824753556; the ABN prefix and spaced formats like ABN 51 824 753 556 are normalized automatically. Results are cached for 25 days like every other country.

Yes. POST /v1/validate/async accepts a single VAT number, and the async batch endpoint accepts up to 200 numbers per batch on Pro or 1,000 on Business. Both return 202 immediately with a request_id, then deliver the result to your configured webhook URL when validation completes, as validation.completed, validation.failed, or batch.completed events. Every delivery is signed with HMAC-SHA256 so you can verify it came from Avatcado, and the dashboard logs every delivery attempt and lets you replay failed deliveries. This is useful for large batch processing, for checkout flows where you want to keep 1-3 second VIES lookups out of the critical path, and for resilience against registry downtime: if a country's service is temporarily unavailable, Avatcado queues the request and retries automatically. Async validation and webhooks are available on Pro and Business plans and require a live avat_live_ key; test keys are rejected with a 403.

Yes. The /v1/validate/batch endpoint accepts up to 50 VAT/GST numbers in a single request and is available on Pro and Business plans. Each number is validated independently against the appropriate registry (VIES, HMRC, BFS, Bronnoysund, or ABR), and results come back in the same order as the input array. The response is always HTTP 200: individual failures such as an upstream timeout or an invalid format appear inline as per-item error objects instead of failing the whole request, so one bad number never costs you the other 49 results. Per-item meta shows cache state, since one item may be a fresh lookup while another comes from the 25-day cache. Duplicates in the input are deduplicated: only unique numbers are validated and counted against your monthly quota, while the response still returns one result per input item. Pass requester_vat_number once to receive consultation numbers for the EU items. For larger batches, use async batch validation.