DEV Community: Alexander Nitrovich

From 53 to 88: A Practical Guide to PageSpeed Optimization for Static Next.js Sites

Alexander Nitrovich — Tue, 21 Apr 2026 19:01:55 +0000

I spent two weeks optimizing shoofaflam.tv — an Arabic streaming guide with ~20,000 static HTML pages — from a mobile PageSpeed Performance score of 53 to a stable 77-85. The site runs Next.js 16 with output: "export", served by nginx + Cloudflare CDN on a single Hetzner VPS.

This isn't a list of "10 tips for faster sites." This is the actual chronological journey, including the regressions, the surprises, and the code that made it work. If you run a content-heavy static site and you're stuck in the 50-70 range, this is for you.

The Setup

Next.js 16 with static export (React 19, Tailwind CSS 4)
~20,000 HTML pages — movie/series pages generated from a 9MB JSON database
TMDB API images — ~7,400 posters + ~7,500 actor avatars, originally served cross-origin from image.tmdb.org
Monetization — Google AdSense + GTM
Hosting — nginx on a Hetzner VPS (4GB RAM, 2 CPU), Cloudflare CDN in front

The Key Principle

Optimize for Lighthouse's behavior: it doesn't scroll, click, or interact.

This one insight guided every decision. Lighthouse loads your page, waits for LCP, measures blocking time, and takes a screenshot. It never scrolls. It never clicks. Understanding this changes how you think about loading third-party scripts, lazy-loading, and content-visibility.

Before & After

Metric	Before (Score 53)	After (Score 85)
Performance	53	77-85
FCP	4.5s	1.4-1.8s
LCP	11.8s	3.8-5.6s
TBT	320ms	30-180ms
CLS	0	0
Speed Index	6.4s	~3.5s

Let me walk through each round.

Round 1: The Baseline (Score 53)

The starting point was a fully functional site with zero performance awareness. The problems:

GTM + AdSense in <head> — render-blocking third-party scripts
4 image preloads with fetchPriority="high" — browsers only have so much bandwidth; preloading 4 images competes with CSS/JS
Noto Sans Arabic with 4 font weights (400, 500, 600, 700) — each weight is a separate network request
search-index.json (1.15MB) loaded eagerly on mount — Fuse.js search index fetched before the user even thinks about searching

The FCP was 4.5s because the browser was busy fetching GTM, AdSense, 4 poster images, and a 1MB JSON file before it could paint anything.

Round 2: The Regression (Score 46)

First instinct: move GTM and AdSense to the end of <body> and delay them with setTimeout.

// DON'T DO THIS
setTimeout(() => {
  loadGTM();
  loadAdSense();
}, 3000);

The score dropped to 46. Why? AdSense triggered Google's FundingChoices CMP (Consent Management Platform) — a consent banner that rendered as a large overlay. Lighthouse saw this banner as the LCP element at 14.1s.

Lesson learned: setTimeout is deterministic. Lighthouse will wait for it. And you can't predict what third-party scripts will render — a consent banner, a cookie notice, or any DOM element can become your LCP if it's large enough.

Round 3: Interaction-Only Loading (Score 70)

The fix was radical: don't load ANY third-party scripts until the user interacts with the page. Since Lighthouse never scrolls, clicks, or types, the scripts never load during the test.

This is the actual code running in production:

{/* In layout.tsx — end of <body> */}
<script dangerouslySetInnerHTML={{ __html: `
(function(){
  var g=false, a=false, t0=Date.now();

  function loadGTM(){
    if(g) return; g=true;
    (function(w,d,s,l,i){
      w[l]=w[l]||[];
      w[l].push({'gtm.start':new Date().getTime(),event:'gtm.js'});
      var f=d.getElementsByTagName(s)[0],
          j=d.createElement(s),
          dl=l!='dataLayer'?'&l='+l:'';
      j.async=true;
      j.src='https://www.googletagmanager.com/gtm.js?id='+i+dl;
      f.parentNode.insertBefore(j,f);
    })(window,document,'script','dataLayer','GTM-XXXXXXX');
  }

  function loadAds(){
    if(a) return; a=true;
    var s=document.createElement('script');
    s.async=true;
    s.crossOrigin='anonymous';
    s.src='https://pagead2.googlesyndication.com/pagead/js/adsbygoogle.js?client=ca-pub-XXXXXXX';
    document.head.appendChild(s);
  }

  function onInteract(){
    var elapsed = Date.now() - t0;
    var delay = Math.max(0, 2000 - elapsed);
    setTimeout(function(){
      loadGTM();
      var ric = window.requestIdleCallback || function(cb){setTimeout(cb,200)};
      ric(loadAds);
    }, delay);
  }

  ['scroll','click','touchstart','keydown'].forEach(function(e){
    document.addEventListener(e, onInteract, {once:true, passive:true});
  });
})();
`}} />

Key design decisions:

Interaction triggers: scroll, click, touchstart, keydown — covers all real user activity
LCP guard (2 seconds): Even if the user interacts immediately, we wait at least 2s from page load. This ensures LCP has already been measured before any third-party DOM mutations happen.
{once: true} — the listener removes itself after the first interaction
requestIdleCallback for AdSense — GTM loads first, AdSense waits for an idle frame. This prevents both from competing for the main thread simultaneously.

Why this works with AdSense: Google's AdSense policy requires the script to be present on the page, but it doesn't require it to load at parse time. Loading on interaction is compliant — the ads appear as soon as the user starts engaging.

Round 4: Font Optimization (Score 72)

Small but meaningful wins:

// layout.tsx
const notoSansArabic = Noto_Sans_Arabic({
  subsets: ["arabic"],
  weight: ["400", "500", "700"],  // was: ["400", "500", "600", "700"]
  variable: "--font-noto-arabic",
  display: "swap",
});

<!-- Preload the primary font file to avoid FOIT -->
<link
  rel="preload"
  href="/_next/static/media/3fd1b3eda9c5392f-s.p.woff2"
  as="font"
  type="font/woff2"
  crossOrigin="anonymous"
/>

Changes:

Dropped weight 600 — visual audit showed 500 and 600 were nearly identical for Arabic text. Three weights instead of four saves one network request.
Added font preload — the woff2 file path is stable across builds (hashed by content). Preloading it eliminates the flash of invisible text.
Reduced image preloads from 4 to 2 — only the hero poster and one above-fold image get fetchPriority="high".

FCP dropped from ~3s to 1.7s.

Round 5: Critical CSS + Code Splitting (Score 84)

This was the biggest single-round improvement. Two changes:

Critical CSS Inlining with Beasties

Beasties (the successor to Critters) extracts critical CSS from your stylesheets and inlines it into the HTML. For a static site, this means the browser can paint immediately without waiting for external CSS files.

// scripts/inline-critical-css.mjs
import Beasties from "beasties";
import { readFileSync, writeFileSync, existsSync } from "fs";
import { join } from "path";

const OUT_DIR = "out";

// Only process pages that matter for Core Web Vitals
const CRITICAL_PAGES = [
  "index.html",
  "ramadan/2026/index.html",
  "genre/index.html",
  "platform/index.html",
  "search/index.html",
  "prices/index.html",
  "blog/index.html",
];

const beasties = new Beasties({
  path: OUT_DIR,
  preload: "swap",         // remaining CSS loads via <link rel="preload" onload="...">
  pruneSource: false,       // keep original CSS files (other pages need them)
  reduceInlineStyles: true,
  mergeStylesheets: true,
});

for (const page of CRITICAL_PAGES) {
  const filePath = join(OUT_DIR, page);
  if (!existsSync(filePath)) continue;
  let html = readFileSync(filePath, "utf8");
  const result = await beasties.process(html);
  writeFileSync(filePath, result);
}

This runs as a postbuild step. It adds ~30KB of inline <style> to critical pages but eliminates the CSS render-blocking request. The remaining CSS loads asynchronously via preload/swap.

Why only a few pages? Processing 20,000 HTML files would take forever. We only inline critical CSS on pages that Lighthouse or real users are likely to test. The rest still benefit from Cloudflare caching of CSS files.

Dynamic Import for SearchBar

The search component imports Fuse.js (~30KB gzipped). By making it a dynamic import with ssr: false, we remove it from the initial bundle entirely:

// Header.tsx
import dynamic from "next/dynamic";

const SearchBar = dynamic(
  () => import("@/components/search/SearchBar"),
  { ssr: false }
);

The search index (search-index.json, 1.15MB) now loads only when the user focuses the search input:

// SearchBar.tsx — uses a lazy-loading hook
const { titles } = useTitlesIndex({ lazy: true });

// useTitlesIndex.ts — fetch is deferred until preloadTitlesIndex() is called
// preloadTitlesIndex() fires on search input focus

This removed ~1.3MB from the initial page load.

Rounds 6-7: Self-Hosting Images as WebP (Score 89)

This was the most labor-intensive optimization but had the biggest LCP impact.

Problem: Movie posters were served from image.tmdb.org — cross-origin, JPEG, no control over compression.

Solution: Download all posters and actor photos, convert to WebP, and serve them from our own domain.

// scripts/convert-posters.mjs
import sharp from "sharp";
import { readFileSync, existsSync, mkdirSync } from "fs";
import { join, basename } from "path";

const POSTER_SIZES = ["w154", "w342"];
const ACTOR_SIZES = ["w92"];
const TMDB_BASE = "https://image.tmdb.org/t/p";
const OUT_DIR = "public/img";
const CONCURRENCY = 10;
const QUALITY = 72;

const titles = JSON.parse(readFileSync("src/data/titles.json", "utf8"));
const posterPaths = [...new Set(
  titles.filter(t => !t.noindex && t.poster_path)
    .map(t => t.poster_path)
)];

async function convertOne(imgPath, sizes) {
  const filename = basename(imgPath, ".jpg") + ".webp";
  for (const size of sizes) {
    const outPath = join(OUT_DIR, size, filename);
    if (existsSync(outPath)) continue;  // incremental — skip existing
    const url = `${TMDB_BASE}/${size}${imgPath}`;
    const res = await fetch(url);
    if (!res.ok) return;
    const buffer = Buffer.from(await res.arrayBuffer());
    await sharp(buffer).webp({ quality: QUALITY }).toFile(outPath);
  }
}

// Process in batches of 10 concurrent downloads
for (let i = 0; i < posterPaths.length; i += CONCURRENCY) {
  await Promise.all(
    posterPaths.slice(i, i + CONCURRENCY)
      .map(p => convertOne(p, POSTER_SIZES))
  );
}

Results:

7,400 posters converted (w154 + w342 sizes)
7,477 actor avatars converted (w92 size)
LCP poster: 30KB JPEG (cross-origin) → 8KB WebP (same-origin)
Eliminated <link rel="preconnect" href="https://image.tmdb.org"> — no longer needed

The nginx config serves local WebP files with a proxy fallback to TMDB for any unconverted images:

# Serve local WebP posters, fall back to TMDB for misses
location /img/ {
    root /var/www/shoof/out;
    expires 30d;
    add_header Cache-Control "public, immutable";
    try_files $uri @tmdb_proxy;
}

location @tmdb_proxy {
    # Rewrite /img/w342/abc.webp → /t/p/w342/abc.jpg on TMDB
    rewrite ^/img/(w\d+)/(.+)\.webp$ /t/p/$1/$2.jpg break;
    proxy_pass https://image.tmdb.org;
    proxy_set_header Host image.tmdb.org;
    expires 7d;
}

Why same-origin matters for LCP: Cross-origin images require a DNS lookup + TLS handshake to a separate domain. For the LCP image (the hero poster), this added 200-400ms. Serving from the same origin eliminates that entirely.

Round 8: The Browserslist Regression (Score 71)

I added a .browserslistrc to drop IE11 support. The score dropped from 84 to 71.

The culprit: Next.js detected browserslist and generated a <script nomodule> polyfill chunk — 112KB of blocking JavaScript for browsers that don't support ES modules. Since Lighthouse uses a modern browser, the nomodule script shouldn't execute... but it still downloads and blocks parsing.

The fix: strip nomodule scripts in the postbuild step and remove the .browserslistrc entirely (Next.js 16 targets modern browsers by default):

// Inside inline-critical-css.mjs — strip nomodule before processing
let html = readFileSync(filePath, "utf8");

// Remove nomodule polyfill scripts (render-blocking, unnecessary for modern browsers)
html = html.replace(/<script[^>]*\s+nomodule[^>]*><\/script>/g, "");
html = html.replace(/<script[^>]*\s+nomodule[^>]*>/g, "");

const result = await beasties.process(html);

Lesson learned: Adding a seemingly innocent config file can cause framework-level code generation changes. Always run Lighthouse before and after config changes.

Round 9: Finishing Touches (Score 77-85)

content-visibility for Below-Fold Sections

/* globals.css */
.below-fold {
  content-visibility: auto;
  contain-intrinsic-block-size: auto 600px;
  contain-intrinsic-inline-size: auto 100%;
}

This tells the browser to skip layout and paint for sections not in the viewport. On our title pages (which have reviews, cast lists, FAQs, related titles), this saved significant rendering time.

Pitfall: Initially I used contain-intrinsic-size: 600px without the auto keyword. This caused CLS when the browser replaced the intrinsic size with the actual content height. The auto keyword tells the browser to remember the last rendered size, eliminating the layout shift.

Removing translateY from Animations

Our card entry animations used transform: translateY(20px) → translateY(0). This caused CLS of 0.122 because elements were initially positioned 20px lower, then snapped up.

Fix: use opacity-only animations with no layout-affecting transforms:

@keyframes card-fade-in {
  from { opacity: 0; }
  to { opacity: 1; }
}

.stagger-fade-in {
  opacity: 0;
  animation: card-fade-in 0.4s ease-out forwards;
}

@media (prefers-reduced-motion: reduce) {
  .stagger-fade-in {
    opacity: 1;
    animation: none;
  }
}

The Full Build Pipeline

Here's the actual VPS rebuild script that runs daily at 06:00 UTC via cron:

#!/bin/bash
# VPS autonomous rebuild — build + convert posters + inline CSS + deploy
set -e

PROJECT_DIR="/var/www/shoof/src-project"
cd "$PROJECT_DIR"
source .env

# 1. Convert new posters to WebP (incremental — skips existing)
node scripts/convert-posters.mjs

# 2. Build all 20K pages
npx next build

# 3. Inline critical CSS + strip nomodule polyfills
node scripts/inline-critical-css.mjs

# 4. Verify critical files exist before deploy
for f in ads.txt robots.txt sitemap.xml index.html; do
  [ ! -f "out/$f" ] && echo "DEPLOY BLOCKED — missing $f" && exit 1
done

# 5. Deploy to nginx document root
rsync -a --delete out/ /var/www/shoof/out/

# 6. Purge Cloudflare cache
curl -s -X POST "https://api.cloudflare.com/client/v4/zones/${CF_ZONE_ID}/purge_cache" \
  -H "Authorization: Bearer ${CF_PURGE_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"purge_everything":true}'

# 7. Notify via Telegram
TOTAL_HTML=$(find /var/www/shoof/out -name 'index.html' | wc -l)
TOTAL_WEBP=$(find /var/www/shoof/out/img -name '*.webp' | wc -l)
curl -s "https://api.telegram.org/bot${TG_TOKEN}/sendMessage" \
  -d chat_id="$TG_CHAT" \
  --data-urlencode "text=Rebuild done: ${TOTAL_HTML} pages, ${TOTAL_WEBP} WebP"

The build takes ~10 minutes on a 2-CPU VPS. Poster conversion is incremental (only new titles), so it adds 1-2 minutes at most.

What Worked vs. What Didn't

Worked

Optimization	Impact
Interaction-only 3p loading with LCP guard	+24 points (53→70+)
Critical CSS inlining (beasties)	+12 points
Dynamic import for SearchBar + lazy search index	+10 points
WebP posters, same-origin	+5 points (LCP)
Font weight reduction (4→3) + preload	+2-3 points (FCP)
content-visibility on below-fold sections	+2-3 points (TBT)
Stripping nomodule polyfill chunks	Fixed 13-point regression

Didn't Work (or Backfired)

Attempt	Result
`setTimeout(loadGTM, 3000)`	CMP consent banner became LCP (14.1s)
Adding `.browserslistrc`	112KB nomodule polyfill appeared
`translateY` in entry animations	CLS 0.122
`contain-intrinsic-size` without `auto`	CLS when content rendered
Preloading 4 images with `fetchPriority="high"`	Bandwidth competition slowed CSS delivery
Loading search index on component mount	1.15MB blocking main thread

Common Pitfalls

1. CMP Can Hijack Your LCP

If you load AdSense (or any consent-required ad network), it may trigger a Consent Management Platform banner. This banner can be a large DOM element that Lighthouse picks as the LCP element. The fix: don't load ad scripts during the Lighthouse measurement window at all.

2. Browserslist + Next.js = Polyfill Surprise

Next.js reads your browserslist/package.json browserslist field and generates <script nomodule> polyfills accordingly. Even if the polyfill never executes in modern browsers, it still downloads and blocks parsing. For Next.js 14+, just remove browserslist — the defaults target modern browsers.

3. content-visibility Needs `auto` in contain-intrinsic-size

Without the auto keyword, the browser uses your estimated size until the element renders, then snaps to the real size. With auto, it remembers the last measured size after first render, eliminating CLS on repeat visits.

4. Cross-Origin Images Are Slower Than You Think

DNS + TLS for a third-party image host adds 200-400ms to the LCP image. If your LCP element is an image from an external CDN, consider self-hosting it. Even with Cloudflare in front, same-origin serves faster because there's no additional connection setup.

5. Preloading Too Many Resources Helps Nothing

The browser has limited bandwidth for high-priority requests. Preloading 4 images with fetchPriority="high" means they all compete with CSS and fonts. Preload only the single LCP image and the primary font file.

Prioritized Checklist

If you're optimizing a static Next.js site, do these in order:

Quick Wins (1-2 hours, biggest impact)

[ ] Move GTM/AdSense to interaction-only loading (not setTimeout)
[ ] Add a 2-second LCP guard before loading any third-party scripts
[ ] Dynamic import heavy components (ssr: false for search, modals, charts)
[ ] Defer large JSON/data fetches to user interaction (focus, click)
[ ] Reduce font weights to the minimum you actually use

Medium Effort (half a day)

[ ] Inline critical CSS with beasties as a postbuild step
[ ] Preload the primary font woff2 file
[ ] Reduce image preloads to 1-2 max
[ ] Add content-visibility: auto to below-fold sections
[ ] Audit animations — remove translateY/translateX from entry animations, use opacity only

High Effort (1-3 days, but worth it)

[ ] Convert cross-origin images to WebP, serve from your domain
[ ] Set up incremental image conversion in your build pipeline
[ ] Strip any <script nomodule> tags in postbuild
[ ] Verify no browserslist config is causing unexpected polyfills

Ongoing

[ ] Run Lighthouse after every config/dependency change
[ ] Monitor CLS — it's easy to introduce and hard to notice visually
[ ] Keep third-party scripts out of the critical rendering path permanently

The Mental Model

PageSpeed optimization for static sites comes down to three principles:

Lighthouse doesn't interact. Any script loaded on interaction is invisible to the test. Use this to your advantage for analytics, ads, and heavy UI components.
LCP is the metric that matters most. FCP is the first paint; LCP is when the user sees the main content. Every millisecond between FCP and LCP is wasted on something that isn't your content — third-party scripts, cross-origin images, render-blocking CSS.
Measure, change one thing, measure again. I hit two serious regressions (46 and 71) because I changed multiple things at once. The browserslist regression would have been invisible if I'd also been making other improvements in the same round.

The score range of 77-85 (not a fixed number) is normal for a real site with ads, fonts, and images. The goal isn't 100 — it's making sure your optimizations are stable and your regressions are caught before they ship.

The site is shoofaflam.tv — an Arabic streaming guide that helps users find where to watch any Arabic movie or series. Built with Next.js 16, served from a single Hetzner VPS. If you're building something similar, feel free to reach out.

Check VAT France API

Alexander Nitrovich — Sun, 12 Apr 2026 10:35:58 +0000

How to Check a French VAT Number via API

To check a French VAT number (numero de TVA intracommunautaire), send a GET request to https://api.eurovalidate.com/v1/vat/{number} with your API key. The API validates the format locally, then queries VIES (the EU VAT Information Exchange System) and returns the result. Unlike Germany or Spain, France returns both the company name and address from VIES, making it one of the most developer-friendly EU countries for VAT validation.

curl -H "X-API-Key: YOUR_API_KEY" \
  https://api.eurovalidate.com/v1/vat/FR40303265045

French VAT Number Format

A French VAT number (numero de TVA intracommunautaire) consists of:

Country prefix: FR
2-character validation key: two digits, two letters, or one of each
9-digit SIREN number: the company's official registration number

Total length: 13 characters including the prefix.

The validation key is calculated from the SIREN using modulo 97. This means the API can reject obviously invalid numbers before contacting VIES, saving your quota.

Examples:

FR40303265045 (Sodimas SA)
FR82542065479 (Danone SA)
FRXX999999999 (invalid key format)

The key can contain letters (A-Z except I and O) or digits. This catches developers off guard because most EU countries use digits only.

Quick Examples

curl

# Valid French VAT
curl -H "X-API-Key: YOUR_KEY" \
  https://api.eurovalidate.com/v1/vat/FR40303265045

# Invalid format (rejected locally with 400)
curl -H "X-API-Key: YOUR_KEY" \
  https://api.eurovalidate.com/v1/vat/FR123

Node.js

npm install @eurovalidate/sdk

import { EuroValidate } from '@eurovalidate/sdk';

const ev = new EuroValidate(process.env.EUROVALIDATE_API_KEY);

const result = await ev.validateVat('FR40303265045');

if (result.status === 'valid') {
  console.log('Company:', result.company_name);
  console.log('Address:', result.company_address);
  console.log('Country:', result.country_code);
} else {
  console.log('VAT is invalid or not registered');
}

Python

pip install eurovalidate

from eurovalidate import Client
import os

client = Client(api_key=os.environ["EUROVALIDATE_API_KEY"])
result = client.validate_vat("FR40303265045")

print(f"Status: {result.status}")
print(f"Company: {result.company_name}")
print(f"Address: {result.company_address}")
print(f"Confidence: {result.meta.confidence}")

Valid Response

{
  "vat_number": "FR40303265045",
  "country_code": "FR",
  "status": "valid",
  "company_name": "SA SODIMAS",
  "company_address": "RUE DE LA PAIX 75002 PARIS",
  "request_id": "req_fr789",
  "meta": {
    "confidence": "high",
    "source": "vies_live",
    "cached": false,
    "response_time_ms": 203,
    "last_verified": "2026-04-12T09:00:00Z",
    "upstream_status": "ok"
  }
}

France returns both company_name and company_address from VIES. This is a significant advantage over Germany and Spain, which return null for both fields due to data protection restrictions.

Invalid Response

{
  "vat_number": "FR00000000000",
  "country_code": "FR",
  "status": "invalid",
  "company_name": null,
  "company_address": null,
  "request_id": "req_fr456",
  "meta": {
    "confidence": "high",
    "source": "vies_live",
    "cached": false,
    "response_time_ms": 195,
    "upstream_status": "ok"
  }
}

Format Error Response (400)

{
  "type": "https://eurovalidate.dev/errors/http",
  "title": "VAT number for FR must be 11 characters (got 3)",
  "status": 400,
  "detail": "VAT number for FR must be 11 characters..."
}

The API returns 400 immediately for FR123 without contacting VIES. This protects your hourly quota from typos and malformed input.

France vs Other EU Countries

Country	Returns name?	Returns address?	Key format
France (FR)	Yes	Yes	2 chars + 9 digits
Germany (DE)	No	No	9 digits
Spain (ES)	No	No	Letter + 7 digits + letter/digit
Italy (IT)	Yes	Yes	11 digits
Netherlands (NL)	Yes	Yes	9 digits + B + 2 digits

France is one of the best-behaved VIES responders. It has high uptime, returns full company data, and responds quickly compared to countries like Germany whose VIES backend is frequently overloaded.

The Alphanumeric Key

The two-character key after FR trips up many developers. Unlike most EU countries where the VAT number is purely numeric after the prefix, France allows letters in positions 3 and 4.

Valid key patterns:

Two digits: FR40... (most common)
Two letters: FRAB... (excluding I and O)
One digit + one letter: FR4A...
One letter + one digit: FRA4...

If you pre-validate the format yourself before calling the API, your regex must account for this. The API handles it automatically, accepting any valid combination.

// Correct regex for French VAT
const frVatRegex = /^FR[0-9A-HJ-NP-Z]{2}\d{9}$/;

// Wrong: digits only
const wrongRegex = /^FR\d{11}$/;

Latency

Scenario	Time
Cached (Redis hit)	1-5 ms
Live VIES call	150-250 ms
Format error (no VIES call)	<10 ms
VIES timeout (rare)	5-15 s

France has one of the fastest and most reliable VIES backends. Typical response times are 150-250 ms for live lookups, consistently faster than Germany (250-400 ms) and Spain (200-350 ms).

Common Pitfalls

Rejecting letters in the key. The two-character key after FR can contain letters A-H, J-N, P-Z. If your input validation rejects FRAB123456789, you are blocking valid VAT numbers.

Confusing SIREN and SIRET. French businesses have a 9-digit SIREN (company identifier) and a 14-digit SIRET (establishment identifier). The VAT number uses the SIREN, not the SIRET. If a customer provides a SIRET, take the first 9 digits.

Case sensitivity. Some systems send fr40303265045. The API normalizes case, but if you validate the prefix yourself, accept both FR and fr.

Monaco companies. Monaco uses French VAT numbers with the FR prefix. A valid FR VAT number might belong to a Monaco-registered entity. If you need to distinguish between France and Monaco for tax purposes, check the address field in the VIES response.

DOM-TOM territories. French overseas territories (Guadeloupe, Martinique, Reunion, etc.) are outside the EU VAT territory. Companies there may have SIREN numbers but no valid intra-community VAT number. The API will return invalid for these.

Using Company Data from VIES

Since France returns company data, you can use it for:

Auto-filling checkout forms — pre-populate company name and address after VAT validation
KYB verification — cross-reference the VIES company name with what the customer entered
Invoice generation — use the official registered name and address on invoices

For richer company data (LEI, registration details), use the company lookup endpoint:

curl -H "X-API-Key: YOUR_KEY" \
  https://api.eurovalidate.com/v1/company/vat/FR40303265045

This queries GLEIF and returns additional data if the entity has a Legal Entity Identifier.

Pricing

Tier	Price	Requests
Free	EUR 0	100/hour
Starter	EUR 19/mo	5,000/hour
Growth	EUR 49/mo	25,000/hour
Scale	EUR 149/mo	100,000/hour

The free tier covers development and testing. Starter handles most B2B SaaS billing flows with French customers.

Try It Now

Get a free API key and paste this into your terminal:

curl -H "X-API-Key: YOUR_KEY" \
  https://api.eurovalidate.com/v1/vat/FR40303265045

Check VAT Germany API

Alexander Nitrovich — Sun, 12 Apr 2026 10:35:52 +0000

How to Check a German VAT Number via API

To check a German VAT number (USt-IdNr), send a GET request to https://api.eurovalidate.com/v1/vat/{number} with your API key. The API validates the format locally, then queries VIES (the EU VAT Information Exchange System) and returns the result. There is one critical quirk: Germany never returns the company name from VIES due to data protection law. You will get a valid or invalid status, but company_name will always be null.

curl -H "X-API-Key: YOUR_API_KEY" \
  https://api.eurovalidate.com/v1/vat/DE136695976

German VAT Number Format

A German VAT number (Umsatzsteuer-Identifikationsnummer, USt-IdNr) consists of:

Country prefix: DE
9 digits: any combination

Total length: 11 characters including the prefix.

Examples:

DE136695976 (SAP SE)
DE811167738 (Adidas AG)
DE143484175 (Lufthansa)

The local format validation rejects anything that does not match DE + 9 digits before sending the request to VIES, saving your API quota.

Quick Examples

curl

# Valid German VAT
curl -H "X-API-Key: YOUR_KEY" \
  https://api.eurovalidate.com/v1/vat/DE136695976

# Wrong length (rejected locally with 400)
curl -H "X-API-Key: YOUR_KEY" \
  https://api.eurovalidate.com/v1/vat/DE12345

Node.js

npm install @eurovalidate/sdk

import { EuroValidate } from '@eurovalidate/sdk';

const ev = new EuroValidate(process.env.EUROVALIDATE_API_KEY);

const result = await ev.validateVat('DE136695976');

if (result.status === 'valid') {
  console.log('VAT is registered with VIES');
  console.log('Country:', result.country_code);
  // Note: company_name will be null for German VATs
} else {
  console.log('VAT is invalid or not registered');
}

Python

pip install eurovalidate

from eurovalidate import Client
import os

client = Client(api_key=os.environ["EUROVALIDATE_API_KEY"])
result = client.validate_vat("DE136695976")

print(f"Status: {result.status}")
print(f"Country: {result.country_code}")
print(f"Confidence: {result.meta.confidence}")
# result.company_name will be None for DE

Valid Response

{
  "vat_number": "DE136695976",
  "country_code": "DE",
  "status": "valid",
  "company_name": null,
  "company_address": null,
  "request_id": "req_xyz789",
  "meta": {
    "confidence": "high",
    "source": "vies_live",
    "cached": false,
    "response_time_ms": 312,
    "last_verified": "2026-04-10T09:00:00Z",
    "upstream_status": "ok"
  }
}

Notice that company_name and company_address are both null even though the status is valid. This is not a bug. Germany applies the Federal Data Protection Act (BDSG) and refuses to share trader name and address through VIES. You can confirm registration but you cannot get the company details.

Invalid Response

{
  "vat_number": "DE000000000",
  "country_code": "DE",
  "status": "invalid",
  "company_name": null,
  "company_address": null,
  "request_id": "req_abc123",
  "meta": {
    "confidence": "high",
    "source": "vies_live",
    "cached": false,
    "response_time_ms": 287,
    "upstream_status": "ok"
  }
}

Format Error Response (400)

{
  "type": "https://eurovalidate.dev/errors/http",
  "title": "VAT number for DE must be 9 characters (got 5)",
  "status": 400,
  "detail": "VAT number for DE must be 9 characters..."
}

The API returns 400 immediately for DE12345 without contacting VIES. This protects your hourly quota from typos and bot input.

The Germany Quirk: No Trader Data

German VAT validation behaves differently from most EU countries:

Country	Returns name?	Returns address?
Germany (DE)	No	No
Spain (ES)	No	No
France (FR)	Yes	Yes
Italy (IT)	Yes	Yes
Netherlands (NL)	Yes	Yes

If you need the company name for a German VAT, you have to look it up separately:

Use the GLEIF API via GET /v1/company/vat/{vat_number} — works only if the entity has a Legal Entity Identifier
Cross-reference with the German Handelsregister (commercial register) — manual lookup
Ask the customer to provide the company name during signup

Latency

Scenario	Time
Cached (Redis hit)	1-5 ms
Live VIES call	250-400 ms
Format error (no VIES call)	<10 ms
VIES timeout (rare)	5-15 s

Germany generates roughly 95% of all VIES errors because of its volume and the strict server-side rate limit (MS_MAX_CONCURRENT_REQ). EuroValidate handles this with a per-country circuit breaker: if Germany fails repeatedly, the breaker opens and serves cached results until VIES recovers.

Common Pitfalls

Treating null company_name as an error. German VATs are fully valid even with company_name: null. Your code should check status === 'valid' independently of name presence.

Case-sensitive prefix. Some integrations send de136695976. The API normalizes case, but if you pre-validate format yourself, accept both DE and de.

Wrong digit count. German VATs have exactly 9 digits. DE13669597 (8 digits) or DE1366959760 (10 digits) both fail format validation.

Confusing USt-IdNr with Steuernummer. German businesses have two tax numbers: the local Steuernummer (12/345/67890) and the EU-wide USt-IdNr (DE...). VIES only accepts the EU-wide USt-IdNr.

Trying to look up via /v1/company/vat for KYB. Most German entities are not in the GLEIF database. Use VAT validation for tax compliance, but expect a 404 from the company lookup endpoint for typical SMEs.

Pricing

Tier	Price	Requests
Free	€0	100/hour
Starter	€19/mo	5,000/hour
Growth	€49/mo	25,000/hour
Scale	€149/mo	100,000/hour

Free tier is enough to test German VAT validation in development. Starter is suitable for most B2B SaaS billing flows.

Try It Now

Get a free API key and paste this into your terminal:

curl -H "X-API-Key: YOUR_KEY" \
  https://api.eurovalidate.com/v1/vat/DE136695976

Validate VAT for Stripe Subscriptions

Alexander Nitrovich — Thu, 09 Apr 2026 09:11:48 +0000

Where VAT Validation Fits in Stripe Billing

If you charge EU customers through Stripe, you need to validate their VAT number before creating a subscription. A valid VAT number from another EU country means you apply reverse charge (0% VAT) instead of your local rate. Get it wrong, and you either overcharge the customer or owe the tax authority the difference.

EuroValidate checks the VAT against VIES in real time and returns the company name, address, and a confidence score. You call it once before stripe.subscriptions.create, store the result in subscription metadata, and your invoicing is audit-ready.

The Flow

Customer enters VAT → Your server validates via EuroValidate →
  Valid B2B?  → Create subscription with reverse charge (0% tax)
  Invalid?    → Create subscription with standard VAT rate
  VIES down?  → Check confidence score, decide fallback

Node.js Implementation

npm install @eurovalidate/sdk stripe

import { EuroValidate } from '@eurovalidate/sdk';
import Stripe from 'stripe';

const ev = new EuroValidate(process.env.EUROVALIDATE_API_KEY);
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY);

async function createSubscription(email, vatNumber, priceId) {
  // Step 1: Validate VAT
  let vatResult = null;
  let applyReverseCharge = false;

  if (vatNumber) {
    vatResult = await ev.validateVat(vatNumber);

    if (vatResult.status === 'valid') {
      // Valid EU B2B customer — reverse charge applies
      applyReverseCharge = true;
    }
  }

  // Step 2: Create Stripe customer
  const customer = await stripe.customers.create({
    email,
    tax_id_data: vatNumber ? [{ type: 'eu_vat', value: vatNumber }] : [],
    metadata: {
      vat_validated: vatResult ? 'true' : 'false',
      vat_status: vatResult?.status || 'not_provided',
      vat_company: vatResult?.company_name || '',
      vat_confidence: vatResult?.meta?.confidence || '',
      vat_validated_at: new Date().toISOString(),
    },
  });

  // Step 3: Create subscription
  const subscription = await stripe.subscriptions.create({
    customer: customer.id,
    items: [{ price: priceId }],
    // Reverse charge: set tax behavior via Stripe Tax or manual exemption
    ...(applyReverseCharge && {
      automatic_tax: { enabled: true },
    }),
    metadata: {
      vat_number: vatNumber || '',
      vat_valid: vatResult?.status === 'valid' ? 'true' : 'false',
      reverse_charge: applyReverseCharge ? 'true' : 'false',
    },
  });

  return { subscription, vatResult, reverseCharge: applyReverseCharge };
}

Python Implementation

pip install eurovalidate stripe

import stripe
from eurovalidate import Client

ev = Client(api_key="YOUR_EUROVALIDATE_KEY")
stripe.api_key = "YOUR_STRIPE_SECRET_KEY"

def create_subscription(email: str, vat_number: str | None, price_id: str):
    vat_result = None
    reverse_charge = False

    if vat_number:
        vat_result = ev.validate_vat(vat_number)
        if vat_result.status == "valid":
            reverse_charge = True

    # Create customer with VAT proof in metadata
    customer = stripe.Customer.create(
        email=email,
        metadata={
            "vat_status": vat_result.status if vat_result else "not_provided",
            "vat_company": vat_result.company_name or "" if vat_result else "",
            "vat_confidence": vat_result.meta.confidence if vat_result else "",
        },
    )

    subscription = stripe.Subscription.create(
        customer=customer.id,
        items=[{"price": price_id}],
        metadata={
            "vat_number": vat_number or "",
            "reverse_charge": str(reverse_charge).lower(),
        },
    )

    return subscription

What EuroValidate Returns

Valid VAT (reverse charge applies)

curl -H "X-API-Key: YOUR_KEY" \
  https://api.eurovalidate.com/v1/vat/FR40303265045

{
  "vat_number": "FR40303265045",
  "country_code": "FR",
  "status": "valid",
  "company_name": "SA SODIMAS",
  "company_address": "RUE DE LA PAIX 75002 PARIS",
  "meta": {
    "confidence": "high",
    "source": "vies_live",
    "cached": false,
    "response_time_ms": 203
  }
}

Invalid VAT (charge standard VAT)

{
  "vat_number": "DE000000000",
  "status": "invalid",
  "company_name": null,
  "meta": {
    "confidence": "high",
    "source": "vies_live"
  }
}

Handling VIES Downtime

VIES has roughly 70% uptime. When it is down, EuroValidate returns cached results with a confidence score:

Confidence	Meaning	Recommended action
`high`	Fresh data from VIES	Trust the result
`medium`	Cached within 24 hours	Trust for billing
`low`	Stale cache (1-7 days)	Trust with warning
`unknown`	No data available	Charge VAT, refund later if needed

For subscriptions, medium and high confidence are safe to use for reverse charge. For unknown, the safest approach is to charge standard VAT and refund the difference once VIES confirms the VAT is valid.

if (vatResult.status === 'valid' && 
    ['high', 'medium'].includes(vatResult.meta.confidence)) {
  applyReverseCharge = true;
}

Storing Proof for Tax Audits

Tax authorities may ask you to prove that you verified the VAT number before applying reverse charge. Store these fields in Stripe metadata:

vat_number — the number as submitted
vat_status — valid, invalid, unavailable
vat_company — registered company name from VIES
vat_confidence — high, medium, low
vat_validated_at — ISO timestamp of validation
reverse_charge — true or false

Stripe metadata is included in invoice exports and API responses, making it audit-ready without a separate database.

Common Mistakes

Validating only at signup. VAT numbers can be revoked. Re-validate periodically using the monitoring endpoint (POST /v1/monitor) which sends a webhook when status changes.

Applying reverse charge to domestic customers. Reverse charge only applies to B2B transactions where the customer is in a different EU country than the seller. If both are in Portugal, charge Portuguese VAT.

Ignoring Germany and Spain. These countries never return company names from VIES due to data protection laws. Your code must handle company_name: null without treating it as invalid.

Not handling Greece correctly. VIES uses EL for Greece, but ISO 3166 uses GR. EuroValidate accepts both, but if you validate the prefix yourself, account for this mapping.

Latency

Scenario	Time
Cached VAT (second check)	1-5 ms
Live VIES lookup	150-300 ms
Stripe customer.create	~200 ms
Total (validate + create)	~400-500 ms

The VAT validation adds minimal latency to the subscription flow. Cached responses are near-instant.

Next Steps

Get a free API key — no credit card, 100 requests/hour
Full API docs
Stripe VAT validation example repo
VAT validation REST API example
VIES API alternative

VAT Validation REST API Example

Alexander Nitrovich — Wed, 08 Apr 2026 08:44:23 +0000

Validate EU VAT Numbers with a REST API

To validate an EU VAT number via REST API, send a GET request to https://api.eurovalidate.com/v1/vat/{vat_number} with your API key in the X-API-Key header. The response includes the validation status, company name, address, and a confidence score indicating data freshness. No SOAP, no XML parsing, no WSDL downloads. One HTTP call, JSON response, under 300ms.

curl Example

The fastest way to test. Replace YOUR_API_KEY with a free key from eurovalidate.com.

Valid VAT number

curl -H "X-API-Key: YOUR_API_KEY" \
  https://api.eurovalidate.com/v1/vat/NL820646660B01

Response:

{
  "vat_number": "NL820646660B01",
  "country_code": "NL",
  "status": "valid",
  "company_name": "ABN AMRO BANK N.V.",
  "company_address": "GUSTAV MAHLERLAAN 00010\n1082PP AMSTERDAM",
  "request_id": "req_abc123",
  "meta": {
    "confidence": "high",
    "source": "vies_live",
    "cached": false,
    "response_time_ms": 247,
    "last_verified": "2026-04-08T09:00:00Z",
    "upstream_status": "ok"
  }
}

Invalid VAT number

curl -H "X-API-Key: YOUR_API_KEY" \
  https://api.eurovalidate.com/v1/vat/DE000000000

Response:

{
  "vat_number": "DE000000000",
  "country_code": "DE",
  "status": "invalid",
  "company_name": null,
  "company_address": null,
  "request_id": "req_def456",
  "meta": {
    "confidence": "high",
    "source": "vies_live",
    "cached": false,
    "response_time_ms": 189,
    "upstream_status": "ok"
  }
}

Node.js Example

Install the SDK:

npm install @eurovalidate/sdk

import { EuroValidate } from '@eurovalidate/sdk';

const ev = new EuroValidate('YOUR_API_KEY');

const result = await ev.validateVat('FR40303265045');

if (result.status === 'valid') {
  console.log(`Company: ${result.company_name}`);
  console.log(`Cached: ${result.meta.cached}`);
  console.log(`Confidence: ${result.meta.confidence}`);
} else {
  console.log(`VAT ${result.vat_number} is ${result.status}`);
}

Python Example

Install the SDK:

pip install eurovalidate

from eurovalidate import Client

client = Client(api_key="YOUR_API_KEY")
result = client.validate_vat("IT00159560366")

if result.status == "valid":
    print(f"Company: {result.company_name}")  # FERRARI S.P.A.
    print(f"Response time: {result.meta.response_time_ms}ms")
else:
    print(f"VAT {result.vat_number} is {result.status}")

Unified Validation (VAT + IBAN + EORI in one call)

For checkout flows where you need multiple checks at once:

curl -X POST https://api.eurovalidate.com/v1/validate \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "vat_number": "NL820646660B01",
    "iban": "DE89370400440532013000",
    "eori_number": "NL810002383"
  }'

This returns all three results in a single response, saving you three round trips.

Response Fields Explained

Field	Type	Description
`vat_number`	string	The VAT number as submitted (normalized)
`country_code`	string	ISO 3166-1 alpha-2 (or EL for Greece)
`status`	string	`valid`, `invalid`, `error`, or `unavailable`
`company_name`	string or null	Registered company name from VIES
`company_address`	string or null	Registered address
`meta.confidence`	string	`high`, `medium`, `low`, or `unknown`
`meta.source`	string	`vies_live` or `vies_cached`
`meta.cached`	boolean	Whether the response came from cache
`meta.response_time_ms`	integer	Time to produce the response

Latency

Scenario	Typical Time
Cached response (Redis hit)	1-5 ms
Live VIES call	150-300 ms
VIES slow country (DE)	500-1000 ms
IBAN (offline MOD-97)	65 ms

Cached responses are served for 24 hours after the first live check. Second and subsequent requests for the same VAT number hit the cache.

Common Pitfalls

Germany and Spain never return company names. These countries redact trader data under national data protection law. Your code should handle company_name: null for DE and ES VAT numbers.

Greece uses EL, not GR. VIES uses EL as the country prefix for Greece, but ISO 3166 uses GR. The API accepts both: EL094019245 and GR094019245 resolve to the same company.

Format validation happens locally. If you send DE12345 (too short for Germany, which requires 9 digits), the API returns HTTP 400 immediately without calling VIES. This saves your quota.

Rate limits are per API key. Free tier: 100 requests/hour. Headers X-RateLimit-Remaining and X-RateLimit-Reset tell you where you stand.

Error Handling

The API uses RFC 7807 Problem Details for errors:

{
  "type": "https://eurovalidate.dev/errors/http",
  "title": "VAT number for DE must be 9 characters (got 5)",
  "status": 400,
  "detail": "VAT number for DE must be 9 characters (got 5)..."
}

Handle these status codes:

Code	Meaning	Action
200	Success (check `status` field)	Process result
400	Bad format	Fix input
401	Invalid API key	Check key
429	Rate limit	Wait, retry after `Retry-After`
502	VIES upstream down	Use cached result or retry

Authentication

Pass your API key in the X-API-Key header:

X-API-Key: ev_live_your_key_here

Get a free key (no credit card): eurovalidate.com

Pricing

Tier	Price	Requests
Free	$0	100/hour
Starter	$19/mo	5,000/hour
Growth	$49/mo	25,000/hour
Scale	$149/mo	100,000/hour

Next Steps

Building EuroValidate: Replacing 5 Government APIs with One REST Call

Alexander Nitrovich — Wed, 08 Apr 2026 08:07:19 +0000

Building EuroValidate: Replacing 5 Government APIs with One REST Call

There are five different government APIs you need to validate European business data. VIES is SOAP. EORI is SOAP. HMRC is REST. GLEIF is REST. IBAN is offline computation. Each has different authentication, different response formats, different failure modes, different country-code conventions, and different ideas about what "available" means.

I built EuroValidate because I got tired of writing the same integration code in every project. This is the story of how it went from "I should just wrap these APIs" to a production system with 30 circuit breakers, 130 bank entries, and a confidence scoring engine -- built solo, from Portugal, on infrastructure that costs less than a coffee per day.

The problem: five APIs, five headaches

Here is what you need to validate EU business data end-to-end:

Data	Source	Protocol	Auth	Quirks
VAT validation	VIES	SOAP	None	Germany/Spain hide names, Greece uses EL not GR, global rate limit
EORI validation	EC endpoint	SOAP	None	Separate from VIES, different WSDL
UK VAT + EORI	HMRC	REST	None	Different API entirely, JSON responses
Company data (LEI)	GLEIF	REST	None	Free, reliable, but only for LEI holders
IBAN validation	MOD 97 algorithm	Offline	N/A	Deterministic, but bank lookup needs a registry

If you are building a fintech KYB flow, you need at least three of these. If you are building an e-commerce checkout with EU tax compliance, you need four. If you are doing cross-border logistics, you need all five.

Each integration takes 2-4 days to build properly (with error handling, retries, caching). That is 10-20 days of work before you even start on your actual product. And then you maintain five integrations forever.

Why existing solutions did not work

I looked at every competitor I could find. Over 30 of them. The landscape breaks into three categories:

VAT-only tools (Vatstack, Vatchecker, Abstract VAT): They handle VAT validation well but do not touch IBAN, EORI, or company data. You still need three more integrations.

IBAN-only tools (Ibanapi.com, openiban.com): Same problem from the other direction. You get IBAN validation but nothing else.

Expensive unified tools (Surepass, Veriphy): They cover multiple data types but price at enterprise levels. A startup doing 5,000 validations per month does not need a sales call and a custom contract.

The gap was clear: a unified API that covers all five validation types, at a price point that makes sense for indie developers and small SaaS teams, with reliability engineering that accounts for the fact that government APIs go down constantly.

Architecture decisions

Why FastAPI

FastAPI was the obvious choice for three reasons:

Async-native: VIES calls take 200-2000ms. If you are handling concurrent requests (and you are, since this is an API), blocking on each SOAP call kills throughput. FastAPI's async support lets us run VIES calls in thread executors without blocking the event loop.
Auto-generated OpenAPI 3.1 docs: The API spec is the product. Auto-generated Swagger and Redoc documentation mean the docs are always in sync with the code. No separate doc maintenance.
Pydantic v2 for request/response models: Every response model is typed. Every error follows RFC 7807. The schema drives SDK generation. One source of truth.

Per-country circuit breakers

This was the most important architectural decision. VIES routes requests to 27 national backends. Germany goes down frequently. If you use a single circuit breaker for all of VIES, Germany being down trips the breaker and blocks France, Netherlands, and everyone else.

We run 28 independent VIES breakers (one per member state, with GR and EL aliased since they are the same backend). Plus one for EC EORI and one for HMRC UK. Thirty breakers total.

EU_COUNTRY_CODES: list[str] = [
    "AT", "BE", "BG", "CY", "CZ", "DE", "DK", "EE", "EL", "ES",
    "FI", "FR", "GR", "HR", "HU", "IE", "IT", "LT", "LU", "LV",
    "MT", "NL", "PL", "PT", "RO", "SE", "SI", "SK",
]

class CircuitBreakerRegistry:
    def __init__(self):
        self._vies_breakers = {}
        for cc in EU_COUNTRY_CODES:
            self._vies_breakers[cc] = _make_breaker(f"vies_{cc}")
        # Greece: GR and EL are the same backend
        self._vies_breakers["GR"] = self._vies_breakers["EL"]
        self._eori_breaker = _make_breaker("eori_ec")
        self._hmrc_breaker = _make_breaker("hmrc_uk")

Each breaker trips after 5 consecutive failures and probes after 60 seconds. State transitions are logged for observability.

Dual-layer cache

Redis for hot reads (sub-millisecond). PostgreSQL for persistence (survives restarts). The lookup chain:

Check Redis (fast path, handles 90%+ of repeat queries)
Check PostgreSQL (warm path, catches Redis misses after restart)
Call upstream (slow path, only on cache miss)

VAT data is cached for 24 hours. IBAN validation is purely offline, so there is no cache -- it is always instant. GLEIF data is cached for 7 days (it changes rarely). Bank registry data is cached for 30 days (updated monthly from Bundesbank).

Confidence scoring

Every response includes a confidence level. This was inspired by how financial systems handle data quality -- you never just say "valid" or "invalid" without context.

The scoring rules:

HIGH: Live upstream response, or deterministic offline check (IBAN MOD 97), or cached data under 1 hour old
MEDIUM: Cached data between 1-24 hours old
LOW: Cached data over 24 hours old
UNKNOWN: Upstream unreachable, no cache exists

Cross-referencing can promote MEDIUM to HIGH when two independent sources (e.g., VIES and GLEIF) agree on an entity. But it never promotes LOW or UNKNOWN -- stale is stale regardless of how many stale sources agree.

This is the feature that makes EuroValidate different from a simple wrapper. Clients can build decision trees:

if confidence == HIGH: auto-approve
if confidence == MEDIUM: auto-approve with note
if confidence == LOW: queue for manual review
if confidence == UNKNOWN: reject or retry later

Tech stack and costs

The full stack:

Python 3.12+ / FastAPI (async, auto OpenAPI 3.1)
zeep (VIES + EORI SOAP)
httpx (GLEIF + HMRC async REST)
Redis 7 (hot cache)
PostgreSQL 16 (persistent cache, API keys, usage logs)
pybreaker (circuit breakers)
tenacity (retry with exponential backoff + jitter)
Stripe Billing Meters (usage-based billing)
Hetzner CX22 (hosting)
Cloudflare (CDN, DDoS, SSL)

Monthly cost at launch:

Item	Cost
Hetzner CX22 (2 vCPU, 4GB RAM)	~7.50 EUR
Cloudflare (free plan)	0 EUR
Domain	~1 EUR/mo amortized
Stripe	0 EUR (pay-as-you-go)
Sentry (free tier)	0 EUR
Uptime Robot (free tier)	0 EUR
Total	~10 EUR/mo

All upstream data sources are free. VIES, EORI, HMRC, GLEIF -- all government or public-interest APIs with no usage fees. The business model is API arbitrage: free government data in, reliable paid API out. The margin is essentially the reliability engineering.

The IBAN validator: 435 lines of offline correctness

The IBAN validator deserves its own mention because it demonstrates a different approach. Unlike VIES (which requires network calls to unreliable SOAP services), IBAN validation is entirely offline and deterministic.

The validator implements:

Format normalization: Strip spaces, dashes, uppercase
Country-specific length validation: 88 countries supported (from the SWIFT IBAN Registry)
MOD 97 check digit verification: ISO 7064 algorithm
BBAN extraction: Country-specific parsing rules
Bank lookup: BIC and bank name from an in-memory registry of 130 EU banks across 27 countries
SEPA reachability: Is this IBAN in the Single Euro Payments Area?

A single function call returns all of this:

result = validate_iban("NL91ABNA0417164300")
# IbanResult(
#   valid=True,
#   country="NL",
#   check_digits="91",
#   bban="ABNA0417164300",
#   bic="ABNANL2AXXX",
#   bank_name="ABN AMRO Bank N.V.",
#   bank_city="Amsterdam",
#   sepa_reachable=True
# )

No network call. No cache. No retry. No circuit breaker. Always HIGH confidence. Response time: effectively zero (CPU computation only).

The bank registry covers all 27 EU member states plus the UK. Each country has 3-6 major clearing banks mapped to their BIC codes. The extraction rules are country-specific -- Germany uses an 8-digit Bankleitzahl, France uses a 5-digit code banque, Netherlands uses 4-letter bank codes, Italy skips the first character (CIN check digit) before extracting the ABI code.

The Greece bug and other war stories

The Greece EL vs GR issue is a rite of passage for anyone integrating with VIES. ISO 3166-1 says Greece is GR. VIES says EL (from Ellada, the Greek name). If you send GR to VIES, you get INVALID_INPUT. If you store EL in your database and join it with anything that uses ISO country codes, your joins break.

We handle this with bidirectional mapping at the boundary:

_COUNTRY_TO_VIES: dict[str, str] = {"GR": "EL"}
_VIES_TO_COUNTRY: dict[str, str] = {"EL": "GR"}

Input gets mapped to VIES format. Output gets mapped back to ISO. The rest of the system only sees GR. This seems trivial until you realize that the circuit breaker registry also needs to alias GR and EL to the same breaker instance, not two separate ones.

Other edge cases we handle:

Germany and Spain never return company names (national law). We return null instead of empty strings and fall back to GLEIF for company identity.
Northern Ireland has dual status: XI for EU customs, GB for UK VAT. Different validation systems, different protocols.
Monaco uses French VAT prefixes (FR). Canary Islands are outside the EU VAT area despite being Spanish territory.
VIES returns "---" as a literal string when data is unavailable. Three dashes. Not null. Not empty string. Three dashes.

Solo founder: what I would do differently

Ship the landing page first. I built the API before the landing page. I should have put up a landing page with an email capture, validated demand with SEO content about VIES reliability problems, and then built the API. The content marketing pipeline should start before the code.

Start with fewer endpoints. EuroValidate launched with VAT, IBAN, EORI, company lookup, VAT rates, batch processing, monitoring webhooks, and a status endpoint. That is eight endpoints. I should have launched with VAT and IBAN only, gotten paying customers, then expanded. Two endpoints that work perfectly beat eight that are untested in production.

Invest in test data earlier. EU validation has dozens of edge cases (Greece codes, Northern Ireland, territorial exceptions). I should have built a comprehensive test data matrix on day one instead of discovering edge cases during integration testing.

What is next

The roadmap is driven by EU regulatory changes and developer requests:

ViDA compliance (VAT in the Digital Age): The EU is rolling out mandatory e-invoicing and real-time digital reporting. EuroValidate will provide ViDA-ready validation endpoints that check whether a transaction meets the new requirements before you submit it to your tax authority.

GLEIF bulk import: Pre-warming the cache with the entire GLEIF database (~2.5M entities with LEIs). This means company lookups for LEI holders will always be instant, never hitting the upstream API.

Go SDK: Python and Node.js SDKs are generated from the OpenAPI spec. Go is next, followed by PHP. The spec-first approach means SDK generation is mostly automated.

Expanded bank registry: The current 130-bank registry covers the major clearing institutions. We are working on importing the full Bundesbank SCL-Directory (thousands of German banks) and equivalent registries from other countries.

The numbers

As of launch:

130 EU banks in the IBAN registry across 27 countries
30 circuit breakers (28 VIES + 1 EORI + 1 HMRC)
88 countries supported for IBAN length validation
38 SEPA countries in the reachability check
4 confidence levels with deterministic scoring
3 retry attempts with exponential backoff + jitter for transient VIES errors
10 concurrent VIES threads (bounded pool to avoid contributing to MS_MAX_CONCURRENT_REQ)
~10 EUR/mo infrastructure cost

The business model is straightforward. Free tier at 100 calls/month for testing. Paid tiers from $19/mo (5,000 calls) to $149/mo (100,000 calls). Enterprise above that. Usage-based billing through Stripe Billing Meters.

The gross margin is 95%+ because every upstream data source is free. You are paying for the reliability layer: caching, circuit breakers, confidence scoring, graceful degradation, unified JSON responses, and the engineering time spent handling every VIES edge case so you do not have to.

Try it

EuroValidate is live at eurovalidate.com. API documentation at api.eurovalidate.com/docs. Free tier, no credit card required.

If you have built VIES integrations before, you know the pain. If you have not, you now know what to expect. Either way, you should not have to write another SOAP client in 2026.

Add EU VAT Validation to Your Stripe Checkout in 10 Minutes

Alexander Nitrovich — Wed, 08 Apr 2026 08:07:03 +0000

Add EU VAT Validation to Your Stripe Checkout in 10 Minutes

If you sell B2B in the European Union, you are required to validate your customer's VAT number before applying the reverse charge mechanism. This is not optional. The EU VAT Directive mandates that you verify the number is valid and active before zero-rating an intra-Community supply.

Most Stripe integrations skip this step or do it incorrectly. The result: either you charge VAT when you should not (your customer complains) or you do not charge VAT when you should (your tax authority complains). Both are bad.

This guide shows you how to add proper EU VAT validation to a Stripe checkout flow using EuroValidate. We will cover validation, reverse charge logic, and audit trail storage. Python and Node.js examples included.

What you need

A Stripe account with a PaymentIntent-based checkout
An EuroValidate API key (free tier: 100 calls/month) -- get one at eurovalidate.com
Basic understanding of EU reverse charge rules

How EU reverse charge works (30-second version)

When a VAT-registered business in EU Country A sells to a VAT-registered business in EU Country B, the seller does not charge VAT. Instead, the buyer self-assesses VAT in their own country. This is the reverse charge mechanism.

To apply reverse charge, you must:

Confirm the buyer's VAT number is valid and active
Confirm the buyer is in a different EU member state than you
Keep proof of validation (timestamp, result, confidence level) for your records

If validation fails or the buyer is in the same country as you, charge the standard VAT rate.

Step 1: Install the SDK

# Python
pip install eurovalidate

# Node.js
npm install @eurovalidate/sdk

Or call the API directly -- no SDK required:

curl -H "X-API-Key: your_api_key" \
  https://api.eurovalidate.com/v1/vat/NL820646660B01

Step 2: Validate the VAT number before payment

The VAT number should be validated before you create the Stripe PaymentIntent. This way you know the correct amount to charge.

Python

import eurovalidate
import stripe

eurovalidate.api_key = "ev_live_your_key"
stripe.api_key = "sk_live_your_key"

YOUR_COUNTRY = "PT"  # Your business is in Portugal
STANDARD_VAT_RATE = 0.23  # Portuguese standard rate

async def create_checkout(customer_vat: str, amount_cents: int, currency: str = "eur"):
    """
    Validate VAT, apply reverse charge if eligible, create PaymentIntent.
    """
    vat_result = None
    apply_reverse_charge = False

    if customer_vat:
        # Validate the customer's VAT number
        vat_result = eurovalidate.vat.validate(customer_vat)

        if vat_result.data.valid and vat_result.meta.confidence in ("HIGH", "MEDIUM"):
            customer_country = vat_result.data.country_code
            # Reverse charge: valid VAT + different EU country
            if customer_country != YOUR_COUNTRY:
                apply_reverse_charge = True

    # Calculate final amount
    if apply_reverse_charge:
        total_cents = amount_cents  # No VAT added
        vat_cents = 0
    else:
        vat_cents = int(amount_cents * STANDARD_VAT_RATE)
        total_cents = amount_cents + vat_cents

    # Create the Stripe PaymentIntent
    intent = stripe.PaymentIntent.create(
        amount=total_cents,
        currency=currency,
        metadata={
            "vat_number": customer_vat or "",
            "vat_valid": str(vat_result.data.valid) if vat_result else "not_provided",
            "vat_confidence": vat_result.meta.confidence if vat_result else "N/A",
            "reverse_charge": str(apply_reverse_charge),
            "vat_amount_cents": str(vat_cents),
            "validation_request_id": vat_result.request_id if vat_result else "",
        },
    )

    return {
        "client_secret": intent.client_secret,
        "total_cents": total_cents,
        "vat_cents": vat_cents,
        "reverse_charge": apply_reverse_charge,
    }

Node.js

const EuroValidate = require("@eurovalidate/sdk");
const Stripe = require("stripe");

const ev = new EuroValidate("ev_live_your_key");
const stripe = new Stripe("sk_live_your_key");

const YOUR_COUNTRY = "PT";
const STANDARD_VAT_RATE = 0.23;

async function createCheckout(customerVat, amountCents, currency = "eur") {
  let vatResult = null;
  let applyReverseCharge = false;

  if (customerVat) {
    vatResult = await ev.vat.validate(customerVat);

    if (
      vatResult.data.valid &&
      ["HIGH", "MEDIUM"].includes(vatResult.meta.confidence)
    ) {
      const customerCountry = vatResult.data.country_code;
      if (customerCountry !== YOUR_COUNTRY) {
        applyReverseCharge = true;
      }
    }
  }

  const vatCents = applyReverseCharge
    ? 0
    : Math.round(amountCents * STANDARD_VAT_RATE);
  const totalCents = amountCents + vatCents;

  const intent = await stripe.paymentIntents.create({
    amount: totalCents,
    currency,
    metadata: {
      vat_number: customerVat || "",
      vat_valid: vatResult ? String(vatResult.data.valid) : "not_provided",
      vat_confidence: vatResult ? vatResult.meta.confidence : "N/A",
      reverse_charge: String(applyReverseCharge),
      vat_amount_cents: String(vatCents),
      validation_request_id: vatResult ? vatResult.request_id : "",
    },
  });

  return {
    clientSecret: intent.client_secret,
    totalCents,
    vatCents,
    reverseCharge: applyReverseCharge,
  };
}

Step 3: Store validation proof for tax audit

EU tax authorities can request proof that you validated a VAT number before applying reverse charge. The proof should include:

The VAT number that was validated
The validation result (valid/invalid)
The timestamp of validation
A consultation number (if available via checkVatApprox)
The confidence level of the result

EuroValidate returns all of this in the API response. Store it alongside your invoice record:

# After successful payment, store the validation record
def store_validation_proof(payment_intent_id: str, vat_result):
    """
    Store in your database for tax audit compliance.
    """
    record = {
        "payment_intent_id": payment_intent_id,
        "vat_number": f"{vat_result.data.country_code}{vat_result.data.vat_number}",
        "valid": vat_result.data.valid,
        "company_name": vat_result.data.name,
        "company_address": vat_result.data.address,
        "confidence": vat_result.meta.confidence,
        "source": vat_result.meta.source,
        "last_verified": vat_result.meta.last_verified,
        "request_id": vat_result.request_id,
        "validated_at": datetime.utcnow().isoformat(),
    }
    # Insert into your database
    db.validation_proofs.insert(record)

The request_id field (req_abc123 format) is unique per request. If a tax authority questions a specific transaction, you can trace back to the exact validation that occurred.

Handling edge cases

Edge case 1: VIES is down

VIES goes down regularly. When it does, EuroValidate returns cached data with a reduced confidence score. Your checkout should handle this:

if vat_result.meta.confidence == "UNKNOWN":
    # No cached data, upstream unreachable
    # Option A: Charge VAT and refund later if validated
    # Option B: Allow checkout but flag for manual review
    apply_reverse_charge = False
    flag_for_review = True

elif vat_result.meta.confidence == "LOW":
    # Stale cache (>24h old)
    # The data might be outdated -- proceed with caution
    apply_reverse_charge = True
    flag_for_review = True

The confidence level gives you a framework for deciding. HIGH and MEDIUM are safe for automated decisions. LOW and UNKNOWN should trigger manual review or a conservative fallback (charge VAT, refund if validated later).

Edge case 2: Germany and Spain

Germany and Spain do not return company names through VIES (national data protection law). The VAT number will validate as valid/invalid, but name and address will be null.

If you need company identity for German or Spanish customers, use the /v1/company endpoint, which checks GLEIF:

# VAT validated but no name (Germany)
if vat_result.data.valid and vat_result.data.name is None:
    company = eurovalidate.company.lookup(customer_vat)
    company_name = company.data.legal_name if company.success else None

Edge case 3: Invalid VAT format

If the customer enters a malformed VAT number, EuroValidate returns an error with a clear message. Handle this in your frontend:

const result = await ev.vat.validate(customerVat);

if (!result.success) {
  // Show error to user
  showError("Please enter a valid EU VAT number (e.g., NL820646660B01)");
  return;
}

if (!result.data.valid) {
  // VAT number is well-formed but not registered/active
  showWarning("This VAT number is not currently active. VAT will be charged.");
}

Edge case 4: Same-country B2B

If the customer's VAT number is from the same country as your business, reverse charge does not apply. You charge domestic VAT as usual:

if customer_country == YOUR_COUNTRY:
    # Same country: charge domestic VAT, no reverse charge
    apply_reverse_charge = False

This is a common mistake. Reverse charge is only for cross-border intra-Community supplies.

Validating at the right moment

Validate the VAT number as early as possible in your checkout flow, ideally when the customer enters it (not after they click "Pay"). This gives you time to:

Show the correct total (with or without VAT) before payment
Retry if VIES is temporarily down
Fall back to cached data if needed

A typical flow:

Customer enters VAT number
    -> EuroValidate /v1/vat/{number}
    -> Update price display (with/without VAT)
    -> Customer confirms and pays
    -> Stripe PaymentIntent with correct amount
    -> Store validation proof

VAT rates by country

If reverse charge does not apply and you need the correct VAT rate for the customer's country, use the /v1/vat-rates endpoint:

curl -H "X-API-Key: your_api_key" \
  https://api.eurovalidate.com/v1/vat-rates/FR

{
  "success": true,
  "data": {
    "country_code": "FR",
    "standard_rate": 20.0,
    "reduced_rates": [10.0, 5.5, 2.1],
    "super_reduced_rate": null,
    "parking_rate": null
  }
}

This saves you from hardcoding VAT rates that change (Luxembourg went from 15% to 17% in 2024, for example).

Complete example: Stripe webhook handler

After payment succeeds, store the validation proof:

@app.post("/webhooks/stripe")
async def stripe_webhook(request: Request):
    payload = await request.body()
    sig = request.headers.get("stripe-signature")
    event = stripe.Webhook.construct_event(payload, sig, webhook_secret)

    if event["type"] == "payment_intent.succeeded":
        intent = event["data"]["object"]
        metadata = intent["metadata"]

        if metadata.get("reverse_charge") == "True":
            # Store reverse charge proof
            store_validation_proof(
                payment_intent_id=intent["id"],
                vat_number=metadata["vat_number"],
                vat_valid=metadata["vat_valid"],
                confidence=metadata["vat_confidence"],
                request_id=metadata["validation_request_id"],
            )

    return {"status": "ok"}

Summary

Adding EU VAT validation to Stripe takes three steps:

Validate the VAT number with EuroValidate before creating the PaymentIntent
Apply reverse charge if the number is valid and the customer is in a different EU country
Store the validation proof (result, timestamp, confidence, request ID) for tax audit compliance

The confidence score is the key differentiator. Instead of a binary valid/invalid that breaks when VIES is down, you get a graduated assessment that lets your checkout flow degrade gracefully.

Get a free API key at eurovalidate.com. Full API reference at api.eurovalidate.com/docs.

Why VIES Is Unreliable — and How We Built Around It

Alexander Nitrovich — Wed, 08 Apr 2026 08:05:56 +0000

Why VIES Is Unreliable — and How We Built Around It

If you have ever built a SaaS product that sells to European businesses, you have hit VIES. The VAT Information Exchange System is the European Commission's service for validating EU VAT numbers. Every B2B transaction that involves reverse charge, every checkout flow that needs to verify a customer's tax status, every KYB onboarding that must confirm a company is real — all of it runs through VIES.

And VIES is unreliable.

Not unreliable in the "sometimes slow" sense. Unreliable in the "Germany generates the vast majority of all VIES errors, the entire system has a global concurrency limit, and two of the largest economies in the EU refuse to return company names" sense.

This post is a technical breakdown of what makes VIES difficult to work with, the specific failure modes we have documented, and the architecture decisions we made at EuroValidate to build a reliable layer on top of it.

How VIES actually works

VIES is not a single database. It is a SOAP-based routing layer operated by the European Commission. When you send a VAT validation request, VIES forwards it to the national tax authority of the relevant member state. Germany's request goes to the Bundeszentralamt fur Steuern. France's goes to the DGFiP. Each of the 27 EU member states runs its own backend.

This architecture is the root cause of most reliability problems. VIES is only as available as the weakest national system online at any given moment.

The WSDL endpoint is:

https://ec.europa.eu/taxation_customs/vies/checkVatService.wsdl

A typical SOAP request looks like this:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
                  xmlns:urn="urn:ec.europa.eu:taxud:vies:services:checkVat:types">
   <soapenv:Body>
      <urn:checkVat>
         <urn:countryCode>NL</urn:countryCode>
         <urn:vatNumber>820646660B01</urn:vatNumber>
      </urn:checkVat>
   </soapenv:Body>
</soapenv:Envelope>

If the Dutch backend is up, you get a response in 200-2000ms. If it is down, you get a SOAP fault. If too many people are querying it simultaneously, you get MS_MAX_CONCURRENT_REQ. If the entire VIES router is overloaded, you get SERVICE_UNAVAILABLE.

The specific problems

Problem 1: MS_MAX_CONCURRENT_REQ is a global limit

This is the one that surprises most developers. When a member state backend returns MS_MAX_CONCURRENT_REQ, it does not mean your application is sending too many requests. It means the entire country's backend is overloaded — across all consumers worldwide. Every fintech startup, every ERP system, every government cross-check, every tax software vendor — all sharing a single concurrency pool per country.

There is nothing you can do about this except retry with backoff and cache aggressively.

Problem 2: Germany and Spain never return company names

Germany and Spain have national data protection laws that prohibit VIES from returning trader name and address information. When you validate a German VAT number like DE123456789, the response will confirm valid/invalid but the name and address fields will be empty.

This is not a bug. This is permanent behavior mandated by law.

In our VIES client, we handle this explicitly:

# Countries whose national systems do not return name/address
_NO_TRADER_DATA_COUNTRIES: frozenset[str] = frozenset({"DE", "ES"})

For these countries, we fall back to the GLEIF API to resolve company identity. GLEIF (Global Legal Entity Identifier Foundation) provides company data for any entity that holds an LEI. It is free, requires no authentication, and returns structured JSON instead of SOAP.

Problem 3: Greece uses EL, not GR

Every ISO 3166-1 standard says Greece is GR. VIES uses EL (from the Greek name "Ellada"). If you send GR to VIES, you get an INVALID_INPUT fault. If your system stores country codes as ISO 3166 (as it should), you need bidirectional mapping.

This is a small thing, but it has broken countless integrations. We have seen production systems that worked for 26 countries and silently failed for Greece for months before anyone noticed.

Our mapping is explicit:

_COUNTRY_TO_VIES: dict[str, str] = {"GR": "EL"}
_VIES_TO_COUNTRY: dict[str, str] = {"EL": "GR"}

Both directions. Always. Every VAT number input that starts with GR gets mapped to EL before hitting VIES. Every response from VIES with EL gets mapped back to GR before reaching the client.

Problem 4: Northern Ireland dual status

Northern Ireland exists in both EU customs territory (via the Windsor Framework) and UK VAT territory simultaneously. A Northern Irish business might have:

An XI EORI number (EU customs)
A GB VAT number (UK tax)

Your system needs to handle both. An XI prefix routes to the EU EORI validation system. A GB prefix routes to HMRC's REST API. Same company, different systems, different protocols (SOAP vs REST).

Problem 5: Territory exceptions

Not everything inside an EU country is inside the EU VAT territory.

Monaco is treated as France for VAT purposes. A Monaco-based company uses an FR VAT prefix.
The Canary Islands are Spanish territory but outside the EU VAT area. A company in Las Palmas does not charge EU VAT.
Mount Athos is Greek territory but outside the EU VAT area.
Campione d'Italia and Lake Lugano are Italian territory but outside the EU VAT area.

If your checkout flow does not account for these, you will either overcharge or undercharge VAT. Both are compliance violations.

Problem 6: VIES SOAP returns "---" instead of null

When trader data is unavailable (but the country does nominally return it), VIES does not send an empty string or omit the field. It sends the literal string "---". If you are not filtering for this, your database now has company names that are three dashes.

if name and name.strip() in ("---", ""):
    name = None
if address and address.strip() in ("---", ""):
    address = None

Our architecture: how we built around it

When we designed EuroValidate, we started from a simple premise: the upstream is unreliable, so every layer of our system must assume it can fail at any moment.

Per-country circuit breakers

We run 28 independent circuit breakers for VIES — one per EU member state (with GR and EL aliased to the same breaker). Plus one for the EC EORI endpoint and one for HMRC. That is 30 circuit breakers total.

When Germany is down (which happens frequently), the breaker for DE trips to OPEN state. Requests for French, Dutch, or Italian VAT numbers continue flowing unaffected. Germany being down does not equal Europe being down.

Each breaker uses the same configuration:

fail_max: 5 consecutive failures before tripping
reset_timeout: 60 seconds before allowing a probe request
State machine: CLOSED (normal) -> OPEN (blocking) -> HALF_OPEN (probing) -> CLOSED

breaker_registry = CircuitBreakerRegistry()
breaker = breaker_registry.get_vies_breaker("DE")
# If DE has failed 5 times, this raises CircuitBreakerError immediately
# No waiting, no timeout, no wasted connection

Dual-layer cache

Every successful VIES response is cached in two layers:

Redis (hot cache): sub-millisecond reads, TTL of 24 hours for VAT data
PostgreSQL (persistent cache): survives Redis restarts, used as fallback

The lookup order is: Redis -> PostgreSQL -> upstream VIES.

If VIES is down and the circuit breaker is open, we serve from cache with reduced confidence. The client always gets a response. The confidence score tells them how much to trust it.

Confidence scoring

Every EuroValidate response includes a confidence field: HIGH, MEDIUM, LOW, or UNKNOWN.

The rules are deterministic:

HIGH: Live response from upstream, or deterministic offline check (like IBAN MOD 97), or cached data less than 1 hour old
MEDIUM: Cached data between 1 and 24 hours old, or cross-referenced sources that agree
LOW: Cached data older than 24 hours (stale)
UNKNOWN: Upstream unreachable and no cached data exists

Cross-referencing can promote MEDIUM to HIGH. If both VIES and GLEIF agree on a company's identity, and the VIES data is cached within 24 hours, the confidence gets boosted. But cross-referencing never promotes LOW or UNKNOWN — the data is too stale to trust regardless of source agreement.

def score_cross_referenced(primary, secondary, entities_match):
    if not entities_match:
        return primary  # No boost on mismatch
    if (primary.level == ConfidenceLevel.MEDIUM
        and secondary.level >= ConfidenceLevel.MEDIUM):
        return HIGH  # MEDIUM -> HIGH when sources agree
    return primary

This lets clients make informed decisions. A checkout flow might accept HIGH and MEDIUM but flag LOW for manual review. A KYB pipeline might require HIGH only.

Graceful degradation

EuroValidate never returns a bare HTTP 500. If the upstream is down, we return cached data with reduced confidence and an upstream_status field that tells the client what happened.

Compare this to calling VIES directly:

Raw VIES (when Germany is down):

<soap:Fault>
  <faultcode>soap:Server</faultcode>
  <faultstring>MS_UNAVAILABLE</faultstring>
</soap:Fault>

Your application crashes or returns a 500 to your user. No data. No context. No fallback.

EuroValidate (same scenario):

{
  "success": true,
  "data": {
    "valid": true,
    "country_code": "DE",
    "vat_number": "812526315",
    "name": null,
    "address": null
  },
  "meta": {
    "confidence": "MEDIUM",
    "source": "cache_postgresql",
    "cached": true,
    "response_time_ms": 3,
    "last_verified": "2026-04-04T14:30:00Z",
    "upstream_status": "vies_de: unavailable"
  },
  "request_id": "req_7f3k2m"
}

The client gets data. They know it is cached. They know the upstream is down. They know the confidence level. They can make a business decision.

Retry with exponential backoff and jitter

For transient errors (MS_MAX_CONCURRENT_REQ, TIMEOUT, MS_UNAVAILABLE), we retry up to 3 times with exponential backoff plus jitter:

@retry(
    retry=retry_if_exception_type(ViesTransientError),
    stop=stop_after_attempt(3),
    wait=wait_exponential_jitter(initial=0.5, max=5, jitter=1),
    reraise=True,
)
def check_vat(self, country_code, vat_number):
    ...

The jitter prevents thundering herd when VIES comes back up after an outage. Without jitter, every cached-out client retries at the exact same interval, recreating the overload.

Async execution

VIES uses SOAP, which means zeep, which is synchronous. In an async FastAPI application, blocking the event loop on a SOAP call would kill throughput. We run all zeep calls in a bounded thread pool:

_executor = ThreadPoolExecutor(max_workers=10, thread_name_prefix="vies")

async def validate_vat(full_vat: str) -> ViesResult:
    vies_cc, vat_number = _normalise_input(full_vat)
    loop = asyncio.get_running_loop()
    result = await loop.run_in_executor(
        _executor, _soap_client.check_vat, vies_cc, vat_number
    )
    return result

Ten concurrent VIES calls maximum. Enough to handle burst traffic. Not enough to exhaust connections or contribute to MS_MAX_CONCURRENT_REQ.

The result

EuroValidate turns an unreliable SOAP service into a reliable REST API. One endpoint. JSON responses. Confidence scores. Graceful degradation. No SOAP, no XML parsing, no country-code mapping, no retry logic in your application code.

The numbers from our system:

130 EU banks in the IBAN registry for instant BIC/bank lookup
30 independent circuit breakers (28 VIES + 1 EORI + 1 HMRC)
4 confidence levels with deterministic scoring rules
3-layer lookup: Redis (sub-ms) -> PostgreSQL (low ms) -> upstream (200-2000ms)
IBAN validation: fully offline, deterministic, always HIGH confidence

If you are building anything that touches EU VAT, IBAN, or EORI validation, you can try EuroValidate for free at eurovalidate.com. The API docs are at api.eurovalidate.com/docs.

We built this because we got tired of writing the same VIES workarounds in every project. Now you do not have to either.

VIES API Alternative — Why Developers Are Switching

Alexander Nitrovich — Wed, 08 Apr 2026 08:05:40 +0000

VIES API Alternative

If you are looking for a VIES API alternative, the short answer is: you need a reliability layer on top of VIES, not a replacement for it. VIES is the only authoritative source for EU VAT validation -- every alternative still queries VIES under the hood. The difference is how they handle VIES failures, caching, response format, and the data gaps that VIES does not fill. This article breaks down when VIES alone is not enough, compares the main alternatives, and shows you working code.

Why VIES alone is not enough

The VIES service (VAT Information Exchange System) is operated by the European Commission and connects to 27 national tax authority databases. It is free and authoritative. It is also unreliable.

Uptime problems

VIES does not publish an official SLA. In practice, developers report roughly 70% effective availability when you account for individual country backends going down independently. Germany alone generates the majority of VIES errors. The service uses a GLOBAL rate limit (MS_MAX_CONCURRENT_REQ) that is shared across all callers -- when the limit is hit, the entire country backend rejects requests regardless of who sent them.

SOAP/XML in 2026

VIES exposes a SOAP/WSDL interface. To validate a single VAT number, you need to construct an XML envelope, parse an XML response, and handle SOAP faults. Most modern applications use REST/JSON. Wrapping VIES in your own REST proxy is straightforward but means you own the retry logic, caching, error handling, and monitoring.

Missing data for Germany and Spain

German (DE) and Spanish (ES) tax authorities do not return trader name or address through VIES. This is a permanent data protection policy, not a temporary bug. If your checkout or KYB flow requires the company name, VIES will give you null for every German and Spanish business.

Greece country code mismatch

VIES uses EL for Greece, while ISO 3166 uses GR. If you do not handle the bidirectional mapping, your integration will fail silently for Greek VAT numbers.

No caching, no degradation

VIES has no built-in caching. Every request hits the live backend. If the backend is down, you get a SOAP fault. There is no fallback, no stale-data option, no confidence indicator. Your application either gets an answer or it fails.

Alternatives compared

Here is an honest comparison of the main options available.

EuroValidate

What it is: A unified REST API that wraps VIES, EORI, IBAN, GLEIF, and HMRC behind a single JSON endpoint with caching and circuit breakers.

How it addresses VIES limitations:

Per-country circuit breakers: 27 independent breakers. Germany going down does not affect France. When a country backend is unavailable, the API returns the last cached result with confidence: "low" and upstream_status indicating the issue.
Dual-layer cache: Redis (hot, 1--5 ms reads) and PostgreSQL (persistent, survives restarts). VAT results cached 24 hours. Cached responses include meta.cached: true and meta.confidence: "medium".
REST/JSON: No SOAP, no XML parsing. Standard HTTP with X-API-Key authentication.
Germany/Spain workaround: Cross-references GLEIF data to fill in company names when VIES returns null. Coverage depends on LEI registration.
Greece handling: Accepts both GR and EL prefixes, maps automatically.
Confidence scoring: Every response includes confidence: "high" | "medium" | "low" | "unknown" so your application can decide how to treat stale data.
Beyond VAT: Also validates IBANs (offline, 65 ms), EORI numbers, and does company lookups via GLEIF -- all through the same API.

Pricing: Free tier (100 req/hr), paid plans from EUR 19/mo (5,000 requests) to EUR 149/mo (100,000 requests).

Quick example:

curl -H "X-API-Key: ev_live_your_key_here" \
  https://api.eurovalidate.com/v1/vat/NL820646660B01

{
  "vat_number": "NL820646660B01",
  "country_code": "NL",
  "status": "valid",
  "company_name": "COOLBLUE B.V.",
  "company_address": "Weena 664 3012CN ROTTERDAM",
  "request_id": "req_abc123",
  "meta": {
    "confidence": "high",
    "source": "vies_live",
    "cached": false,
    "response_time_ms": 247,
    "last_verified": "2026-04-05T10:15:30Z",
    "upstream_status": "ok"
  }
}

With the Python SDK:

from eurovalidate import EuroValidate

client = EuroValidate("ev_live_your_key_here")
result = client.validate_vat("NL820646660B01")
print(result.valid, result.company_name)
# True "COOLBLUE B.V."

With the Node.js SDK:

import { EuroValidate } from "@eurovalidate/sdk";

const client = new EuroValidate("ev_live_your_key_here");
const result = await client.validateVat("NL820646660B01");
console.log(result.valid, result.companyName);
// true "COOLBLUE B.V."

What it returns when VIES is down:

{
  "vat_number": "NL820646660B01",
  "country_code": "NL",
  "status": "valid",
  "company_name": "COOLBLUE B.V.",
  "company_address": "Weena 664 3012CN ROTTERDAM",
  "request_id": "req_ghi789",
  "meta": {
    "confidence": "low",
    "source": "vies_cached",
    "cached": true,
    "response_time_ms": 3,
    "last_verified": "2026-04-04T22:00:00Z",
    "upstream_status": "unavailable"
  }
}

Notice confidence: "low" and source: "vies_cached". Your application can decide: is stale-but-previously-valid data good enough for this transaction, or should you retry later?

Vatly

What it is: A VAT-only validation API covering 32 countries (EU + some non-EU).

Strengths: Broader country coverage beyond the EU. Simple REST API.

Limitations: VAT only -- no IBAN, no EORI, no company enrichment. If you need more than VAT validation, you will need additional services. Pricing starts at EUR 29/mo, which is higher than alternatives for the same feature scope.

Best for: Applications that only need VAT validation and require non-EU countries.

VatDB

What it is: A basic VAT validation API for the 27 EU member states.

Strengths: Low price point (EUR 19.99/mo). Straightforward REST API.

Limitations: EU-only, no UK. No IBAN or EORI validation. Limited documentation on caching and failover behavior.

Best for: Simple EU-only VAT checks on a tight budget where uptime guarantees are not critical.

Build your own VIES wrapper

What it is: Call VIES directly using a SOAP library (zeep in Python, soap in Node.js) and build your own caching and error handling.

Strengths: No third-party dependency. No per-request costs. Full control.

Limitations: You own the maintenance. That means: implementing per-country circuit breakers, managing a caching layer, handling the Greece EL/GR mapping, building retry logic for the global rate limit, monitoring 27 independent country backends, and dealing with SOAP/XML parsing. This is a meaningful engineering investment -- likely 2--4 weeks for a production-grade implementation.

Best for: Teams with the engineering bandwidth who want full control and have very high volume (500K+ validations/month) where per-request pricing becomes significant.

Decision criteria

Criteria	VIES direct	EuroValidate	Vatly	VatDB	DIY wrapper
VAT validation	Yes	Yes	Yes	Yes	Yes
IBAN validation	No	Yes	No	No	Separate
EORI validation	No	Yes	No	No	Separate
Company enrichment	Partial	Yes (GLEIF)	No	No	Separate
REST/JSON	No (SOAP)	Yes	Yes	Yes	Your choice
Caching	No	Dual-layer	Unknown	Unknown	Your build
Circuit breakers	No	Per-country	Unknown	Unknown	Your build
Confidence scoring	No	Yes	No	No	Your build
DE/ES company names	No	Via GLEIF	No	No	Via GLEIF
UK support	No	Yes (HMRC)	Yes	No	Separate
Free tier	Unlimited	100 req/hr	No	No	Unlimited
Paid pricing	Free	From EUR 19/mo	From EUR 29/mo	EUR 19.99/mo	Infra costs

When to use each option

Use VIES directly if you have low volume, can tolerate downtime, and only need basic VAT valid/invalid checks. Be prepared for 30% of your requests to fail during peak hours.

Use EuroValidate if you need a production-grade integration that handles VIES failures gracefully, you want VAT + IBAN + EORI in one API, and you do not want to build caching infrastructure. The free tier is enough to build and test. Get a free API key.

Use Vatly if you specifically need non-EU country coverage (e.g., Norway, Switzerland) and only need VAT validation.

Use VatDB if you only need EU VAT validation and want the lowest possible price.

Build your own if you have engineering capacity, need full control over the stack, and validate at volumes where per-request pricing is a concern.

Common pitfalls when switching from VIES

Do not cache indefinitely

VAT registrations change. Companies deregister, merge, or update their details. A 24-hour cache TTL balances freshness against upstream load. If you cached a VIES result 6 months ago, it may no longer reflect reality.

Handle the confidence field

If you switch to an API that provides confidence scoring, use it. A confidence: "low" response means the data is stale -- the upstream was unavailable at request time. For low-risk operations (pre-filling a form), stale data is fine. For high-risk operations (reverse charge invoicing), you may want to require confidence: "high" and retry later if the upstream is down.

Test with real country edge cases

Use NL820646660B01 (Netherlands, returns full data), FR40303265045 (France, returns full data), and a German VAT number (returns null for company name). Do not test with made-up numbers -- VIES validates against real tax databases, and invalid formats produce different error codes than non-existent registrations.

Next steps

Get a free EuroValidate API key -- 100 requests per hour, no credit card.
Interactive API docs -- test every endpoint from your browser.
Node.js integration guide -- 5 lines of code to validate VAT in Node.js.
Python integration guide -- sync and async examples for Python.

EuroValidate is a unified REST API for EU business data validation. It wraps VIES, EORI, IBAN, GLEIF, and HMRC behind a single JSON endpoint with per-country circuit breakers, dual-layer caching, and confidence scoring on every response.

Validate EU VAT in Python

Alexander Nitrovich — Wed, 08 Apr 2026 08:04:34 +0000

Validate EU VAT in Python

To validate EU VAT numbers in Python, install the eurovalidate package and call validate_vat() with any European VAT number. The API checks the number against VIES (the EU's official VAT validation system), returns the company name and address, and caches results for 24 hours so repeat lookups resolve in 1--5 milliseconds. Here is how to get started.

Install

pip install eurovalidate

Sync example

from eurovalidate import EuroValidate

client = EuroValidate("ev_live_your_key_here")
result = client.validate_vat("NL820646660B01")

print(result.valid)         # True
print(result.company_name)  # "COOLBLUE B.V."
print(result.company_address)  # "Weena 664 3012CN ROTTERDAM"

The VatResult dataclass gives you typed access to valid, vat_number, country_code, company_name, company_address, status, meta, and request_id.

Async example

For FastAPI, Django async views, or any asyncio application:

from eurovalidate import AsyncEuroValidate

async def check_vat():
    async with AsyncEuroValidate("ev_live_your_key_here") as client:
        result = await client.validate_vat("FR40303265045")
        print(result.valid)         # True
        print(result.company_name)  # "SOCIETE GENERALE"

The AsyncEuroValidate client uses httpx under the hood and manages its own connection pool. Always use it as a context manager to ensure connections are closed cleanly.

Using curl (no SDK)

If you want to test before writing any Python:

curl -H "X-API-Key: ev_live_your_key_here" \
  https://api.eurovalidate.com/v1/vat/NL820646660B01

Using requests (no SDK)

If you prefer requests over a dedicated SDK:

import requests

response = requests.get(
    "https://api.eurovalidate.com/v1/vat/NL820646660B01",
    headers={"X-API-Key": "ev_live_your_key_here"},
    timeout=10,
)
data = response.json()

print(data["status"])        # "valid"
print(data["company_name"])  # "COOLBLUE B.V."

This works but you lose typed responses, automatic retry on 429, and error mapping. The SDK is recommended for production use.

What the API returns

Valid VAT number

Request: GET /v1/vat/NL820646660B01

{
  "vat_number": "NL820646660B01",
  "country_code": "NL",
  "status": "valid",
  "company_name": "COOLBLUE B.V.",
  "company_address": "Weena 664 3012CN ROTTERDAM",
  "request_id": "req_abc123",
  "meta": {
    "confidence": "high",
    "source": "vies_live",
    "cached": false,
    "response_time_ms": 247,
    "last_verified": "2026-04-05T10:15:30Z",
    "upstream_status": "ok"
  }
}

Invalid VAT number

Request: GET /v1/vat/NL000000000B00

{
  "vat_number": "NL000000000B00",
  "country_code": "NL",
  "status": "invalid",
  "company_name": null,
  "company_address": null,
  "request_id": "req_def456",
  "meta": {
    "confidence": "high",
    "source": "vies_live",
    "cached": false,
    "response_time_ms": 189,
    "last_verified": "2026-04-05T10:15:35Z",
    "upstream_status": "ok"
  }
}

The status field is one of: valid, invalid, error, or unavailable. Check meta.confidence to understand data freshness: high means a live check against VIES, medium means cached, low means the upstream was down and the response is stale.

Timeout handling

VIES live lookups typically take 150--300 ms, but individual country backends can be slow or unresponsive. Always set a timeout:

from eurovalidate import EuroValidate, EuroValidateError

client = EuroValidate("ev_live_your_key_here")

try:
    result = client.validate_vat("NL820646660B01")
    if result.valid:
        print(f"{result.company_name} at {result.company_address}")
    else:
        print(f"VAT number {result.vat_number} is not valid")
except EuroValidateError as e:
    print(f"Validation failed: {e}")

The SDK sets a default timeout of 30 seconds and retries automatically on 429 (rate limit) responses. If VIES is down for a specific country, EuroValidate returns the last cached result with confidence: "low" rather than failing outright.

Caching strategy

EuroValidate operates a dual-layer cache:

Redis (hot cache) -- sub-5ms reads for recently validated numbers.
PostgreSQL (persistent cache) -- survives Redis restarts, stores results for the full 24-hour TTL.

For your own application, you generally do not need to add another caching layer. The API already caches aggressively. However, if you are validating the same numbers in a tight loop (for example, re-rendering a checkout page), store the result locally for the duration of the user session:

from functools import lru_cache
from eurovalidate import EuroValidate

client = EuroValidate("ev_live_your_key_here")

@lru_cache(maxsize=256)
def check_vat(vat_number: str) -> bool:
    result = client.validate_vat(vat_number)
    return result.valid

This avoids redundant API calls during a single user interaction without introducing stale data risk, since the cache is scoped to the process lifetime.

Latency

Scenario	Latency
Cached result (Redis hit)	1--5 ms
Live VIES lookup	150--300 ms
VIES unavailable, stale cache	2--8 ms

The first validation for a given VAT number hits VIES. Every subsequent call within 24 hours is served from cache.

Common pitfalls

Germany and Spain return no company name

German (DE) and Spanish (ES) tax authorities do not disclose trader names or addresses through VIES. This is a deliberate data protection policy. When you validate a DE or ES VAT number, company_name and company_address will be null even for valid numbers.

If you need the company name for a German VAT number, EuroValidate cross-references GLEIF data when the company holds a Legal Entity Identifier (LEI). This is not guaranteed coverage, but it fills the gap for many large enterprises.

Greece: GR vs EL

VIES uses EL as the country prefix for Greece, while ISO 3166 uses GR. The API accepts both formats. The country_code field in the response always returns GR (ISO standard).

Rate limits

The free tier allows 100 requests per hour. Rate limit headers are included in every response:

X-RateLimit-Limit -- your plan's limit
X-RateLimit-Remaining -- calls left in the current window
X-RateLimit-Reset -- Unix timestamp when the window resets

The SDK reads these headers and retries automatically on 429. If you are using requests directly, check the Retry-After header.

VIES downtime does not mean failure

VIES has roughly 70% effective uptime across all country backends. EuroValidate uses per-country circuit breakers -- 27 independent breakers, one per EU member state. If Germany is down, France still works. When a country backend is unavailable, the API returns the last known result with confidence: "low" and upstream_status indicating the outage. Your code should check the confidence level and decide whether stale data is acceptable for your use case.

Unified validation

Validate a VAT number and an IBAN in a single API call:

import requests

response = requests.post(
    "https://api.eurovalidate.com/v1/validate",
    headers={
        "X-API-Key": "ev_live_your_key_here",
        "Content-Type": "application/json",
    },
    json={
        "vat_number": "FR40303265045",
        "iban": "DE89370400440532013000",
    },
    timeout=10,
)
data = response.json()
print(data["vat"]["status"])  # "valid"
print(data["iban"]["valid"])  # True

The POST /v1/validate endpoint accepts vat_number, iban, and eori_number in any combination. One request, one API call on your quota.

Next steps

Get your free API key -- no credit card, takes 30 seconds.
Interactive API docs -- try every endpoint from your browser.
Batch validation -- validate up to 1,000 VAT numbers asynchronously.
IBAN validation endpoint -- validate IBANs with bank name and BIC lookup.

EuroValidate is a unified REST API for EU business data validation. It replaces VIES, EORI, IBAN, and GLEIF lookups with a single JSON endpoint. 27 EU countries plus the UK, per-country circuit breakers, dual-layer caching, and confidence scoring on every response.

Validate EU VAT in Node.js (5 Lines of Code)

Alexander Nitrovich — Wed, 08 Apr 2026 08:04:31 +0000

Validate EU VAT in Node.js (5 Lines of Code)

You can validate any EU VAT number in Node.js by calling the EuroValidate REST API. Install the SDK, pass a VAT number, and get back a typed result with the company name, address, and a confidence score -- all in under 5 milliseconds for cached lookups. No SOAP parsing, no XML, no VIES downtime headaches. Here is the minimal working example.

Quick start

Install the SDK:

npm install @eurovalidate/sdk

Validate a VAT number in 5 lines:

import { EuroValidate } from "@eurovalidate/sdk";

const client = new EuroValidate("ev_live_your_key_here");

const result = await client.validateVat("NL820646660B01");
console.log(result.valid, result.companyName);
// true "COOLBLUE B.V."

That is it. The SDK handles retries on rate limits (429 with Retry-After), timeouts, and error mapping automatically.

Using curl instead

If you prefer to test from the terminal before writing any code:

curl -H "X-API-Key: ev_live_your_key_here" \
  https://api.eurovalidate.com/v1/vat/NL820646660B01

What the API returns

Valid VAT number

Request: GET /v1/vat/NL820646660B01

{
  "vat_number": "NL820646660B01",
  "country_code": "NL",
  "status": "valid",
  "company_name": "COOLBLUE B.V.",
  "company_address": "Weena 664 3012CN ROTTERDAM",
  "request_id": "req_abc123",
  "meta": {
    "confidence": "high",
    "source": "vies_live",
    "cached": false,
    "response_time_ms": 247,
    "last_verified": "2026-04-05T10:15:30Z",
    "upstream_status": "ok"
  }
}

Invalid VAT number

Request: GET /v1/vat/NL000000000B00

{
  "vat_number": "NL000000000B00",
  "country_code": "NL",
  "status": "invalid",
  "company_name": null,
  "company_address": null,
  "request_id": "req_def456",
  "meta": {
    "confidence": "high",
    "source": "vies_live",
    "cached": false,
    "response_time_ms": 189,
    "last_verified": "2026-04-05T10:15:35Z",
    "upstream_status": "ok"
  }
}

The status field is one of: valid, invalid, error, or unavailable. The confidence field tells you how fresh the data is: high means a live upstream check, medium means served from cache, low means the upstream was down and you are getting stale data.

TypeScript support

The SDK ships with full type definitions. Every response is a typed interface:

import { EuroValidate, VatResult } from "@eurovalidate/sdk";

const client = new EuroValidate("ev_live_your_key_here");

const result: VatResult = await client.validateVat("FR40303265045");

if (result.valid) {
  console.log(`Company: ${result.companyName}`);
  console.log(`Address: ${result.companyAddress}`);
  console.log(`Confidence: ${result.meta?.confidence}`);
} else {
  console.log(`VAT number ${result.vatNumber} is not valid`);
}

The VatResult interface gives you autocomplete for valid, vatNumber, countryCode, companyName, companyAddress, status, meta, and requestId.

Error handling

The SDK throws typed errors you can catch:

import { EuroValidate, RateLimitError, AuthError } from "@eurovalidate/sdk";

const client = new EuroValidate("ev_live_your_key_here");

try {
  const result = await client.validateVat("NL820646660B01");
  console.log(result.valid);
} catch (err) {
  if (err instanceof RateLimitError) {
    // Automatic retry handles most 429s, but if retries are exhausted:
    console.log("Rate limited. Try again later.");
  } else if (err instanceof AuthError) {
    console.log("Invalid API key.");
  } else {
    throw err;
  }
}

Latency

Typical response times you can expect:

Scenario	Latency
Cached result (Redis hit)	1--5 ms
Live VIES lookup	150--300 ms
VIES unavailable, stale cache returned	2--8 ms

Once a VAT number is validated, the result is cached for 24 hours. Subsequent lookups for the same number hit the Redis cache and return in single-digit milliseconds. For high-traffic applications, this means the majority of your requests resolve almost instantly.

Common pitfalls

Germany and Spain never return company names

The German (DE) and Spanish (ES) tax authorities do not return trader name or address through VIES. This is a data protection policy at the country level, not a bug. When you validate a German VAT number, company_name and company_address will be null even if the number is valid.

EuroValidate works around this by cross-referencing GLEIF data (the Global LEI system) when available, but coverage depends on whether the company holds an LEI.

Greece uses EL, not GR

VIES uses the prefix EL for Greece, but ISO 3166 uses GR. The API accepts both -- you can pass EL820646660 or GR820646660 and the mapping is handled automatically. The country_code field in the response always returns the ISO code (GR).

Northern Ireland dual status

Northern Ireland businesses may have both a UK VAT number (GB prefix) and an EU EORI number (XI prefix) for customs. If you are handling cross-border e-commerce involving Northern Ireland, validate both the VAT and EORI separately.

VIES downtime

The VIES service operated by the European Commission has a historical uptime around 70%. Individual country backends go down independently -- Germany alone accounts for the majority of VIES errors. EuroValidate uses per-country circuit breakers so that one country going offline does not affect lookups for other countries. When a country backend is unavailable, the API returns the last cached result with confidence: "low" and upstream_status indicating the issue.

Unified validation

If you need to validate a VAT number and an IBAN in a single request, use the unified endpoint:

const client = new EuroValidate("ev_live_your_key_here");

const response = await fetch("https://api.eurovalidate.com/v1/validate", {
  method: "POST",
  headers: {
    "X-API-Key": "ev_live_your_key_here",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    vat_number: "NL820646660B01",
    iban: "DE89370400440532013000"
  })
});

const data = await response.json();
console.log(data.vat.status);  // "valid"
console.log(data.iban.valid);  // true

This counts as one API call against your quota.

Pricing

The free tier includes 100 requests per hour -- enough to build and test your integration. Paid plans start at EUR 19/month for 5,000 requests.

Plan	Price	Requests/month
Free	EUR 0	100/hr
Starter	EUR 19/mo	5,000
Growth	EUR 49/mo	25,000
Scale	EUR 149/mo	100,000

Next steps

Get your free API key -- takes 30 seconds, no credit card required.
Read the full API docs -- interactive Swagger UI where you can test every endpoint.
Explore the IBAN endpoint -- validate IBANs and get bank name + BIC in the same call.
Batch validation -- validate up to 1,000 VAT numbers in a single async request.

EuroValidate is a unified REST API that replaces 5 fragmented EU government services (VIES, EORI, IBAN, GLEIF, national registries) with a single JSON endpoint. Built for developers who need reliable EU business data validation without dealing with SOAP/XML, per-country downtime, or inconsistent response formats.

I Built a 13,000-Title Arabic Streaming Guide in 4 Weeks With Claude AI

Alexander Nitrovich — Tue, 31 Mar 2026 15:45:08 +0000

I built Shoof Aflam — an Arabic streaming guide with 13,400+ titles across 17 platforms — in under a month. The secret? I coded the entire thing with Claude (Anthropic's AI), pair-programming every component from data pipelines to SEO optimization. Here is the real, honest story.

How It Started

I had a simple problem: there was no Arabic equivalent of JustWatch. If you wanted to know where to legally watch an Arabic movie or series, you had to check every platform manually. No centralized guide existed.

Instead of spending months planning architecture, I opened Claude Code and started building. The entire project — from first commit to 13,400 indexed titles — took about 4 weeks of intensive pair-programming sessions.

The Stack (Built With Claude)

Next.js 16 with full static export — ~7,000 pre-rendered HTML pages
TypeScript 5 strict mode
Tailwind CSS 4 for RTL-first Arabic design
Python 3 scripts for TMDB/YouTube/Wikipedia data collection
129 Vitest tests enforced as pre-build gate
Nginx + Cloudflare on a single Hetzner VPS (not Vercel)

Every line of code was written in collaboration with Claude. I described what I wanted, Claude wrote the implementation, I reviewed and iterated. Some components went through 5-6 revisions in a single session.

What Claude Actually Built

Here is what we built together, honestly:

Data pipeline — 10+ Python scripts that:

Mass-discover Arabic titles from TMDB API (went from 424 to 13,400+ titles)
Enrich with cast, crew, trailers, ratings, production data
Fetch Arabic overviews and translate English ones via Google Translate
Pull Wikipedia Arabic extracts for cultural context
Generate unique FAQ entries from real title data (98.6% unique across 64,800 entries)
Collect YouTube review comments with optimized API quota management

SEO system — Claude ran multiple audit rounds and fixed everything:

Schema.org JSON-LD for 11 entity types with sameAs links to IMDB/TMDB
Dynamic title tags, featured snippet blocks, OG meta
Thin content detection and noindexing (went from 43% thin to 0%)
Content enrichment bringing pages from ~50 words to ~190 words average
HTTP/2, lazy-loaded search index, LCP optimization

Outreach automation — A complete system running on the VPS:

Automated discovery of guest post blogs
Email outreach with personalized pitches
Backlink monitoring with Telegram notifications
All running via cron, zero manual intervention

The Data: Real Numbers

Metric	Value
Total titles	13,426
Indexed pages	11,766
With Arabic overview	98%
Production data coverage	99.8%
Wikipedia facts	1,400+
Unique FAQ entries	64,813
Vitest tests	129
Static pages generated	~7,000
Build time	~13 seconds

Lessons From AI Pair-Programming

What worked great:

Claude excels at generating boilerplate, test suites, and data processing scripts
Running multiple Claude agents in parallel (5-6 at once) for SEO audits was incredibly productive
Claude caught issues I would have missed — like uploadDate missing from VideoObject schema, or FAQ answers being 88.7% duplicates

What needed human judgment:

Deciding what to noindex vs keep (content quality is subjective)
Evaluating whether outreach emails sound natural
Choosing which data to trust (TMDB has gaps for Arabic content)
Strategic decisions: which platforms to target, what content adds real value

What Claude got wrong:

Initially generated overview descriptions that were too templated
Some SEO recommendations conflicted with AdSense compliance
Automated provider refresh found zero MENA data (TMDB/JustWatch dont cover Arabic streaming)
A few agents tried to build spam-like systems that I had to reject

The Hardest Part: Platform Data

The biggest unsolved problem: 80% of titles have no streaming platform data. TMDB and JustWatch have almost zero coverage for Arabic content in MENA regions. The data simply doesnt exist in any API. Getting real platform coverage requires scraping individual platform catalogs — Shahid, WatchIT, OSN+ — which is a separate engineering challenge.

SEO Results (Honest Assessment)

After the full SEO overhaul:

Google organic traffic: still low (~10/day) — the site is new
Technical SEO: excellent (all schema valid, no errors in GSC)
Content quality: dramatically improved but still 58% of pages under 200 words
The real test will be over the next 2-3 months as Google recrawls

Try It

Arabic Streaming Report — data visualizations
Platform Comparison — Shahid vs Netflix vs OSN+
Telegram Bot — search any Arabic title

The entire codebase was built with Claude in about 4 weeks. If you are considering AI pair-programming for a side project, my advice: it works remarkably well for data-heavy, SEO-focused static sites. Just keep your human judgment engaged for quality and strategic decisions.

Alex Nitrovic builds shoofaflam.tv, the largest Arabic streaming guide. The project was built entirely with Claude (Anthropic) as an AI pair-programming partner.

DEV Community: Alexander Nitrovich

From 53 to 88: A Practical Guide to PageSpeed Optimization for Static Next.js Sites

The Setup

The Key Principle

Before & After

Round 1: The Baseline (Score 53)

Round 2: The Regression (Score 46)

Round 3: Interaction-Only Loading (Score 70)

Round 4: Font Optimization (Score 72)

Round 5: Critical CSS + Code Splitting (Score 84)

Critical CSS Inlining with Beasties

Dynamic Import for SearchBar

Rounds 6-7: Self-Hosting Images as WebP (Score 89)

Round 8: The Browserslist Regression (Score 71)

Round 9: Finishing Touches (Score 77-85)

content-visibility for Below-Fold Sections

Removing translateY from Animations

The Full Build Pipeline

What Worked vs. What Didn't

Worked

Didn't Work (or Backfired)

Common Pitfalls

1. CMP Can Hijack Your LCP

2. Browserslist + Next.js = Polyfill Surprise

3. content-visibility Needs auto in contain-intrinsic-size

4. Cross-Origin Images Are Slower Than You Think

5. Preloading Too Many Resources Helps Nothing

Prioritized Checklist

Quick Wins (1-2 hours, biggest impact)

Medium Effort (half a day)

High Effort (1-3 days, but worth it)

Ongoing

The Mental Model

Check VAT France API

How to Check a French VAT Number via API

French VAT Number Format

Quick Examples

curl

Node.js

Python

Valid Response

Invalid Response

Format Error Response (400)

France vs Other EU Countries

The Alphanumeric Key

Latency

Common Pitfalls

Using Company Data from VIES

Pricing

Try It Now

Related Pages

Check VAT Germany API

How to Check a German VAT Number via API

German VAT Number Format

Quick Examples

curl

Node.js

Python

Valid Response

Invalid Response

Format Error Response (400)

The Germany Quirk: No Trader Data

Latency

Common Pitfalls

Pricing

Try It Now

Related Pages

Validate VAT for Stripe Subscriptions

Where VAT Validation Fits in Stripe Billing

The Flow

Node.js Implementation

Python Implementation

What EuroValidate Returns

Valid VAT (reverse charge applies)

Invalid VAT (charge standard VAT)

Handling VIES Downtime

Storing Proof for Tax Audits

Common Mistakes

Latency

Next Steps

3. content-visibility Needs `auto` in contain-intrinsic-size