Express Middleware for EU VAT Validation

Drop-in Express middleware that validates EU VAT numbers on any route. Extracts VAT from body, query, or header. Supports required and optional modes.

Quick Start

1. Get your API key at eurovalidate.com
2. Clone and install

   git clone https://github.com/eurovalidate/express-vat-middleware.git
   cd express-vat-middleware
   npm install

3. Configure environment

   cp .env.example .env
   # Edit .env with your EuroValidate API key

4. Run

   npm start
   # Server running at http://localhost:3000

What This Does

Reusable middleware that:

• Extracts VAT number from req.body.vat_number, ?vat= query param, or X-VAT-Number header
• Validates against VIES via EuroValidate
• Attaches result to req.vatValidation for downstream use
• Two modes: optional (fail-open) and required (rejects invalid VAT)

Key Code

const { vatValidation } = require("./middleware");

// Optional: validate if provided, pass through if not
const validateVat = vatValidation({
  apiKey: process.env.EUROVALIDATE_API_KEY,
  required: false,
});

// Required: reject request if VAT is missing or invalid
const requireVat = vatValidation({
  apiKey: process.env.EUROVALIDATE_API_KEY,
  required: true,
});

// Use on any route
app.post("/api/orders", validateVat, (req, res) => {
  if (req.vatValidation?.valid) {
    // Apply reverse charge
  }
});

app.post("/api/b2b/invoices", requireVat, (req, res) => {
  // Only valid VAT reaches here
  res.json({ to: req.vatValidation.companyName });
});

Try It

# Optional VAT on order
curl -X POST http://localhost:3000/api/orders \
  -H "Content-Type: application/json" \
  -d '{"product": "widget", "quantity": 10, "vat_number": "NL820646660B01"}'

# VAT lookup via query param
curl "http://localhost:3000/api/vat/check?vat=FR40303265045"

# Required VAT for B2B invoice
curl -X POST http://localhost:3000/api/b2b/invoices \
  -H "Content-Type: application/json" \
  -d '{"vat_number": "NL820646660B01"}'

API Response

The middleware attaches this to req.vatValidation:

{
  "provided": "NL820646660B01",
  "cleaned": "NL820646660B01",
  "valid": true,
  "companyName": "COOLBLUE B.V.",
  "companyAddress": "WEENA 00664 3012CN ROTTERDAM",
  "countryCode": "NL",
  "confidence": "HIGH",
  "source": "vies_live",
  "cached": false,
  "requestId": "req_abc123"
}

Test VAT Numbers

VAT Number	Country	Company
NL820646660B01	Netherlands	Coolblue B.V.
FR40303265045	France	Google France

Links

• EuroValidate API Docs
• Sign Up
• Node.js SDK

License

MIT