Home / Use cases / Node.js

Node.js VAT API — EU VAT Validation in Node.js

Node.js VAT API integration guide: implement EU VAT number validation in a Node.js or Express application using the TaxID REST API. Includes TypeScript types, error handling for VIES downtime, and caching strategy.

Implementation steps

1. 1

   Install node-fetch or use native fetch

   In Node.js 18+ no installation is needed — global fetch is available by default. For Node.js 16 or earlier, add node-fetch v3 (ESM) or v2 (CJS) to your project. Avoid the deprecated node-fetch v1 or the unmaintained isomorphic-fetch package; they lack proper error handling for network timeouts, which matters when VIES member-state nodes are slow.

2. 2

   Create validateVAT helper function

   Write an async function that accepts (country: string, vat: string) and calls GET https://api.taxid.pro/v1/validate/${country}/${vat} with an Authorization: Bearer YOUR_API_KEY header. Type the return value as { valid: boolean; status: 'active' | 'invalid' | 'service_unavailable'; company_name: string | null; company_address: string | null; cached: boolean; request_id: string } so callers get compile-time safety on every field.

3. 3

   Add error handling for VIES unavailability

   Check the status field before using the result: throw a retriable VATServiceUnavailableError when status === 'service_unavailable' so upstream callers (Express middleware, queue workers) can decide whether to retry or fail open. Never silently treat service_unavailable as valid — doing so would zero-rate invoices for customers whose VAT numbers were never actually confirmed with VIES.

4. 4

   Cache results in Redis or memory

   After a successful API call, store the JSON-serialised response in Redis with SETEX vat:${country}:${vat} 86400 <json> for active numbers and SETEX vat:${country}:${vat} 3600 <json> for invalid ones; these TTLs match TaxID's own cache policy. For single-server deployments without Redis, a simple in-process Map with a timestamp-based eviction check is an acceptable lightweight alternative.

Code example

const res = await fetch(
  'http://localhost:3000/api/v1/validate/DE/DE123456789',
  { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }
);
const { valid, status, company_name, company_address } = await res.json();

if (valid) {
  console.log(`Valid EU business: ${company_name}`);
} else if (status === 'service_unavailable') {
  // VIES is temporarily down — retry or allow with manual check
  console.log('VIES unavailable — check back in a few minutes');
} else {
  console.log('Invalid VAT number — charge local tax rate');
}

import requests

res = requests.get(
    "http://localhost:3000/api/v1/validate/DE/DE123456789",
    headers={"Authorization": "Bearer YOUR_API_KEY"}
)
data = res.json()

if data["valid"]:
    print(f"Valid: {data['company_name']}")
elif data["status"] == "service_unavailable":
    print("VIES temporarily unavailable")
else:
    print("Invalid VAT number")

API response

The TaxID API returns a consistent JSON response for every validation request:

{
  "valid": true,
  "status": "active",
  "country_code": "DE",
  "vat_number": "123456789",
  "company_name": "Example GmbH",
  "company_address": "Musterstraße 1, 10115 Berlin",
  "request_date": "2026-05-10T00:00:00.000Z",
  "cached": false,
  "request_id": "req_01j..."
}

Error handling

The API uses a consistent Stripe-style error format. Always handle service_unavailable separately — VIES has occasional downtime and you should not reject valid customers during outages.

Related use cases