@vatverify/vat-rates

Offline VAT number validation and VAT rates for 44 countries. Real checksum algorithms (MOD97, MOD11, Luhn, HMRC 97-55), not just regex. Zero runtime dependencies, TypeScript-first, works in Node, Bun, Deno, Edge, and browsers.

Why this package

• Real checksum validation: MOD11, MOD97, Luhn, HMRC 97-55. Format-only checks catch typos but accept anything with the right shape.
• Zero runtime dependencies: tree-shakes cleanly, tiny footprint.
• Offline: no network calls, no API key, no rate limits.
• Types-first: precise TypeScript types, string-literal unions for country codes, type predicates that narrow.

For live validation (VIES / HMRC / CH UID / Brønnøysund), this package works as the format/checksum pre-check in front of the hosted vatverify API. Use @vatverify/node.

Install

npm install @vatverify/vat-rates

Usage

Look up a rate

import { getRate, getStandardRate, getAllRates } from '@vatverify/vat-rates';

getStandardRate('DE'); // 19
getStandardRate('GB'); // 20

const de = getRate('DE');
// {
//   standard: 19,
//   reduced: [7],
//   super_reduced: null,
//   zero_rated: true,
//   currency: 'EUR',
//   vat_name: 'Umsatzsteuer',
//   ...
// }

Object.keys(getAllRates()).length; // 44

Validate a VAT number

import { validate, validateFormat, validateChecksum } from '@vatverify/vat-rates';

validate('DE811569869');
// { valid: true }

validate('DE81156986');
// { valid: false, errors: ['invalid format'] }

validate('DE811569868');
// { valid: false, errors: ['invalid checksum'] }

// Two-argument form for countries without a prefix (NO, IS):
validate('923609016', 'NO'); // { valid: true }

validateFormat('DE811569869');    // true (regex only, fast)
validateChecksum('DE811569869');  // true (real algorithm)

Country utilities

import {
  countryName, countryNameLocal,
  isEUMember, isKnownCountry,
  getFlag,
} from '@vatverify/vat-rates';

countryName('DE');      // 'Germany'
countryNameLocal('DE'); // 'Deutschland'

isEUMember('DE');       // true
isEUMember('GB');       // false
isEUMember('ZZ');       // false

isKnownCountry('DE');   // true
isKnownCountry('ZZ');   // false

getFlag('DE');          // '🇩🇪'
getFlag('US');          // '🇺🇸' (works for any ISO-2, not just supported countries)

Types

import type { CountryCode, EUMemberCode, Rate, ValidateResult } from '@vatverify/vat-rates';

const code: CountryCode = 'DE';
const euCode: EUMemberCode = 'FR';
// const bad: EUMemberCode = 'GB'; // Type error: GB is not an EU member

API

| Function | Description | |---|---| | getRate(code) | Full rate object or null | | getStandardRate(code) | Number or null | | getAllRates() | Record<CountryCode, Rate> of all 44 | | countryName(code) | English name or null | | countryNameLocal(code) | Local-language name or null | | isEUMember(code) | Type predicate narrowing to EUMemberCode | | isKnownCountry(code) | Type predicate narrowing to CountryCode | | getFlag(code) | Emoji for any valid ISO-2 | | validateFormat(number, country?) | Regex check only | | validateChecksum(number, country?) | Checksum algorithm only | | validate(number, country?) | Combined: returns { valid: true } or { valid: false, errors } | | dataVersion | ISO date of latest data refresh |

Supported countries

| Group | Codes | |---|---| | EU-27 | AT, BE, BG, CY, CZ, DE, DK, EE, EL, ES, FI, FR, HR, HU, IE, IT, LT, LU, LV, MT, NL, PL, PT, RO, SE, SI, SK | | UK & protocol | GB, XI | | EFTA | CH, LI, NO, IS | | Micro-states | AD | | Candidate / other | AL, BA, ME, MK, RS, TR, MD, UA, XK, GE |

Greece uses EL per VIES convention (an alias from GR is accepted at lookup). XI is Northern Ireland under the Brexit protocol.

Offline vs live

This package does offline checks only: format + checksum. It cannot tell you whether a number is registered with a tax authority. For that, every VAT number in every country requires a live registry call (VIES, HMRC, BFS, Brønnøysund), which is what the hosted vatverify API handles.

Other languages

Same data, same functions, idiomatic per language:

• Python: vatverify-rates (source: vat-rates-py)

License

MIT