@vatverify/vat-rates

VAT rates + offline validation for 44 European countries. Real checksum algorithms, zero dependencies.

Part of the vatverify ecosystem — free data layer for the paid live validation API.

Why this package

• Real checksum validation — MOD11, MOD97, Luhn, HMRC 97-55, and more. Not just regex.
• Zero runtime dependencies — tree-shakes cleanly, tiny footprint.
• Offline — no network calls, works in any JS environment.
• 44 countries — EU-27 + Northern Ireland + UK, Switzerland, Liechtenstein, Norway, Iceland, Andorra, and 10 candidate states.
• Types-first — precise TypeScript types exported, string-literal unions for country codes.

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 |

Live validation

This package checks format and checksums — entirely offline. It does not check whether a VAT number is actually registered.

Live verification against VIES, HMRC, the Swiss UID Register, and Brønnøysundregistrene is coming soon via the vatverify API.

License

MIT