Iurii Validates: EU VAT Number Validation in Next.js (VIES API Tutorial)

// naive-vies.ts — do not use in production
const response = await fetch(
  `https://ec.europa.eu/taxation_customs/vies/rest-api/ms/${countryCode}/vat/${vatNumber}`
);
const data = await response.json();
return data.valid; // will be false during downtime, not an error

// lib/vies.ts
import { z } from "zod";
 
const VIES_REST_BASE = "https://ec.europa.eu/taxation_customs/vies/rest-api";
 
// Country codes that VIES uses — note EL for Greece, not GR
const VIES_COUNTRY_CODES = new Set([
  "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",
]);
 
const ViesResponseSchema = z.object({
  isValid: z.boolean(),
  requestDate: z.string(),
  userError: z.string().optional(),
  name: z.string().optional(),
  address: z.string().optional(),
  requestIdentifier: z.string().optional(),
});
 
export type ViesResult =
  | { status: "valid"; name?: string; address?: string }
  | { status: "invalid" }
  | { status: "unavailable"; reason: string };
 
export async function checkVies(countryCode: string, vatNumber: string): Promise<ViesResult> {
  // Normalize: Greece is EL in VIES, not GR
  const normalized = countryCode.toUpperCase() === "GR" ? "EL" : countryCode.toUpperCase();
 
  if (!VIES_COUNTRY_CODES.has(normalized)) {
    return { status: "invalid" };
  }
 
  // Strip the country prefix if the caller included it in vatNumber
  const cleanNumber = vatNumber.replace(/^[A-Z]{2}/i, "").trim();
 
  const controller = new AbortController();
  const timeoutId = setTimeout(() => controller.abort(), 8000); // 8s timeout
 
  try {
    const response = await fetch(`${VIES_REST_BASE}/ms/${normalized}/vat/${cleanNumber}`, {
      signal: controller.signal,
    });
 
    clearTimeout(timeoutId);
 
    if (!response.ok) {
      return { status: "unavailable", reason: `VIES HTTP ${response.status}` };
    }
 
    const raw = await response.json();
    const parsed = ViesResponseSchema.safeParse(raw);
 
    if (!parsed.success) {
      return { status: "unavailable", reason: "Unexpected VIES response shape" };
    }
 
    const data = parsed.data;
 
    // userError appears when the member state database is down
    // MS_UNAVAILABLE, SERVICE_UNAVAILABLE, etc.
    if (data.userError && data.userError !== "VALID") {
      return { status: "unavailable", reason: data.userError };
    }
 
    if (!data.isValid) {
      return { status: "invalid" };
    }
 
    return {
      status: "valid",
      name: data.name ?? undefined,
      address: data.address ?? undefined,
    };
  } catch (error) {
    clearTimeout(timeoutId);
    if (error instanceof Error && error.name === "AbortError") {
      return { status: "unavailable", reason: "VIES timeout" };
    }
    return { status: "unavailable", reason: "Network error" };
  }
}

// lib/vat-cache.ts
import { Redis } from "ioredis";
 
const redis = new Redis(process.env.REDIS_URL!, {
  maxRetriesPerRequest: 2,
  lazyConnect: true,
});
 
// In-memory fallback for when Redis is unavailable
const memoryCache = new Map<string, { result: ViesResult; expiresAt: number }>();
 
const TTL = {
  valid: 60 * 60 * 24 * 7, // 7 days — valid registrations are stable
  invalid: 60 * 60 * 4, // 4 hours — they might fix their number and retry
  unavailable: 60 * 5, // 5 minutes — retry VIES soon
} as const;
 
function cacheKey(countryCode: string, vatNumber: string): string {
  return `vat:${countryCode.toUpperCase()}:${vatNumber.replace(/\s/g, "")}`;
}
 
export async function getCachedVatResult(
  countryCode: string,
  vatNumber: string
): Promise<ViesResult | null> {
  const key = cacheKey(countryCode, vatNumber);
 
  try {
    const cached = await redis.get(key);
    if (cached) return JSON.parse(cached) as ViesResult;
  } catch {
    // Redis unavailable — fall through to memory cache
    const mem = memoryCache.get(key);
    if (mem && mem.expiresAt > Date.now()) return mem.result;
  }
 
  return null;
}
 
export async function setCachedVatResult(
  countryCode: string,
  vatNumber: string,
  result: ViesResult
): Promise<void> {
  const key = cacheKey(countryCode, vatNumber);
  const ttl = TTL[result.status];
 
  try {
    await redis.set(key, JSON.stringify(result), "EX", ttl);
  } catch {
    // Redis unavailable — write to memory cache as fallback
    memoryCache.set(key, { result, expiresAt: Date.now() + ttl * 1000 });
  }
}

// app/api/vat/validate/route.ts
import { NextRequest, NextResponse } from "next/server";
import { z } from "zod";
import { checkVies } from "@/lib/vies";
import { getCachedVatResult, setCachedVatResult } from "@/lib/vat-cache";
import { db } from "@/lib/db";
import { vatValidationLog } from "@/lib/db/schema";
 
const RequestSchema = z.object({
  countryCode: z.string().length(2),
  vatNumber: z.string().min(4).max(20),
});
 
export async function POST(request: NextRequest) {
  const body = await request.json();
  const parsed = RequestSchema.safeParse(body);
 
  if (!parsed.success) {
    return NextResponse.json(
      { error: "Invalid request", details: parsed.error.flatten() },
      { status: 400 }
    );
  }
 
  const { countryCode, vatNumber } = parsed.data;
 
  const cached = await getCachedVatResult(countryCode, vatNumber);
  if (cached) {
    return NextResponse.json({ ...cached, cached: true });
  }
 
  const result = await checkVies(countryCode, vatNumber);
  await setCachedVatResult(countryCode, vatNumber, result);
 
  // Audit log — essential for tax compliance
  // You must be able to prove what VIES returned at the time of a transaction
  await db.insert(vatValidationLog).values({
    countryCode,
    vatNumber,
    result: result.status,
    checkedAt: new Date(),
  });
 
  return NextResponse.json({ ...result, cached: false });
}

// lib/vat-logic.ts
import type { ViesResult } from "./vies";
 
export type VatDecision =
  | { type: "reverse_charge"; buyerVatNumber: string }
  | { type: "domestic_vat"; rate: number }
  | { type: "oss_vat"; rate: number; buyerCountry: string }
  | { type: "pending_verification" }; // VIES unavailable — queue for review
 
interface TaxContext {
  sellerCountryCode: string;
  buyerCountryCode: string;
  buyerVatNumber?: string;
  viesResult?: ViesResult;
}
 
export function determineVatTreatment(ctx: TaxContext): VatDecision {
  const { sellerCountryCode, buyerCountryCode, buyerVatNumber, viesResult } = ctx;
 
  const isSameCountry = sellerCountryCode.toUpperCase() === buyerCountryCode.toUpperCase();
 
  // B2B cross-border with confirmed valid VAT number = reverse charge
  if (!isSameCountry && buyerVatNumber && viesResult?.status === "valid") {
    return { type: "reverse_charge", buyerVatNumber };
  }
 
  // VIES was unavailable — cannot confirm reverse charge eligibility
  if (!isSameCountry && buyerVatNumber && viesResult?.status === "unavailable") {
    return { type: "pending_verification" };
  }
 
  // Domestic sale — always applies local VAT
  if (isSameCountry) {
    return { type: "domestic_vat", rate: getVatRate(sellerCountryCode) };
  }
 
  // Cross-border B2C — destination country rate (OSS)
  return {
    type: "oss_vat",
    rate: getVatRate(buyerCountryCode),
    buyerCountry: buyerCountryCode,
  };
}

npm install eu-vat-rates-data

// lib/vat-rates.ts
import { getRate } from "eu-vat-rates-data";
 
type RateType = "standard" | "reduced" | "super_reduced" | "parking";
 
export function getVatRate(countryCode: string, type: RateType = "standard"): number {
  const code = countryCode.toUpperCase() === "GR" ? "EL" : countryCode.toUpperCase();
  const rate = getRate(code, type);
 
  if (rate === undefined) {
    throw new Error(`No VAT rates found for: ${countryCode}`);
  }
 
  return rate;
}
 
const germanVat = getVatRate("DE"); // 19
const finnishVat = getVatRate("FI"); // 25.5
const greekVat = getVatRate("GR"); // 24 — EL normalization handled internally