Home / Use cases / Custom

Validate VAT numbers before invoice generation

Automatically validate customer VAT numbers before generating B2B invoices. Prevent invalid numbers from appearing on invoices that could be rejected by tax authorities.

Implementation steps

1. 1

   Trigger before invoice creation

   Insert a pre-generation step in your invoicing pipeline that calls GET /api/v1/validate/:country/:vat immediately before rendering or dispatching the invoice. For Stripe Billing, implement this in an invoice.created webhook handler that checks the status and cancels (voids) the invoice via stripe.invoices.voidInvoice() if the VAT number is invalid, preventing an incorrect invoice from ever reaching the customer.

2. 2

   Cache validation result for 24h

   Store the TaxID response in your application cache (Redis or database) using the key invoice_vat:{customer_id} with a TTL of 86400 seconds for active numbers and 3600 seconds for invalid ones, matching TaxID's own cache policy. Check this cache before calling the API so that monthly invoicing runs for thousands of customers do not each independently call the API for the same customer, preserving your API quota and keeping the pipeline fast.

3. 3

   Block invoice if VAT is invalid

   When status is 'invalid', halt the invoicing pipeline for that customer, set a flag (e.g. invoice_blocked_reason: 'invalid_vat') on the customer record, and notify your AR team via email or Slack webhook with the customer name, the invalid VAT number, and the TaxID request_id. Do not silently generate the invoice with a valid-VAT assumption — the tax liability risk of issuing a zero-rated invoice without a confirmed active VAT registration sits with the seller.

4. 4

   Log validation for audit trail

   Persist every validation check to an invoice_vat_audit table with columns: invoice_id, customer_id, country_code, vat_number, status, company_name, request_id, validated_at. Index on invoice_id and validated_at for efficient retrieval during tax audits. EU VAT regulations require records to be kept for at least 10 years, and having the request_id enables you to dispute any challenge by demonstrating you performed a live VIES verification at the time of invoicing.

Code example

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

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

import requests

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

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

API response

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

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

Error handling

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

Related use cases