import { checkVat, checkVats } from '@ambolt/vies';

console.log(await checkVat('DK10150817'));
// { valid: true, countryCode: 'DK', vatNumber: '10150817', checkedAt: '...', source: 'EU VIES' }

const proof = await checkVat('DE811128135', { requester: 'DK10150817' }); // adds consultationNumber
const many = await checkVats(['DK10150817', 'FR40303265045'], { concurrency: 2 });

What it does

Syntax validation offline per member state (format only, no checksums; VIES decides validity). Invalid syntax returns valid: false with reason: 'invalid_syntax' and makes no request.
Normalises spaces, dots and dashes; GR is sent as EL (Greece), XI is Northern Ireland (goods).
Retries with exponential backoff and full jitter on the VIES errors MS_UNAVAILABLE, MS_MAX_CONCURRENT_REQ, TIMEOUT, SERVICE_UNAVAILABLE, GLOBAL_MAX_CONCURRENT_REQ, and on HTTP 429/5xx and network errors (default 4 retries).
checkVats runs a queue with a concurrency limit (default 2, to stay polite to VIES) and keeps input order. One failed number does not reject the batch.
With requester (your own EU VAT number) it uses the POST endpoint and returns VIES' consultation number, which you can keep as proof of the check.
Privacy default: name and address are not returned unless { includeDetails: true }. For sole traders they are personal data. Nothing is stored or logged by this package.

Result shape: { valid, countryCode, vatNumber, consultationNumber?, checkedAt, source: 'EU VIES', name?, address?, reason? }. A batch item that failed is { input, valid: null, error: { code, message, retryable }, checkedAt, source }.

Options: countryCode, requester, includeDetails, retries, baseDelayMs, maxDelayMs, timeoutMs (15000), signal, concurrency (batch).

Errors

checkVat rejects with ViesError (code, retryable, attempts, status) only when the check could not be completed.

code	meaning	retried
MS_UNAVAILABLE	member state's service is down	yes
MS_MAX_CONCURRENT_REQ	member state is at its request limit	yes
GLOBAL_MAX_CONCURRENT_REQ	VIES is at its request limit	yes
SERVICE_UNAVAILABLE	VIES unavailable	yes
TIMEOUT	VIES or the member state timed out	yes
NETWORK	your connection failed	yes
INVALID_REQUESTER	`requester` is not a valid VAT number	no
IP_BLOCKED, VAT_BLOCKED, HTTP_4xx, BAD_RESPONSE, others	VIES refused or answered unexpectedly	no

When retries run out, the last error is thrown (attempts shows how many requests were made). For a hard failure in a batch, check result.valid === null.

Why not validate-vat or pyvat

Facts as checked on 2026-10-05, from the npm and PyPI registries and GitHub:

validate-vat was last published on 2022-08-22 and its GitHub repository no longer resolved.
jsvat is marked deprecated on npm as unmaintained.
pyvat (Python) had its last release on 2024-01-25 and open issues about MS_UNAVAILABLE and MS_MAX_CONCURRENT_REQ errors.

This package targets the current VIES REST API, retries exactly those errors, and is released with tests that mock HTTP only.

Notes

A VIES result is a point-in-time answer from a member-state database. A member state may be unavailable for hours; handle ViesError.
Respect VIES' terms of use and keep concurrency low.

Not legal or tax advice. VIES is a service of the European Commission; not affiliated. MIT. Contact: hello@ambolt.dev. https://ambolt.dev