Home / Use cases / Next.js

Next.js VAT API Integration: Server Components & API Routes

Integrate VAT number validation into Next.js 14 applications using both App Router API routes (server-side proxy) and React Server Components. Covers client-side UX and server-side billing flows.

Implementation steps

1. 1

   Create the API route proxy

   Add app/api/validate-vat/route.ts. Parse the vatNumber from the JSON body, extract the 2-letter country prefix, and call GET https://taxid.dev/api/v1/validate/:country/:vat with the server-side TAXID_API_KEY environment variable. Return only { valid, status, companyName, address } to the client — never the raw response or the request_id (unless you need it for client-side display).

2. 2

   Build the useVatField client hook

   Create a hooks/useVatField.ts file. The hook manages input value, debounced fetch to /api/validate-vat, loading state, and the validation result. Wire it to a controlled input. Expose onValidVat(vatNumber, companyName) callback for the parent form to capture the validated VAT details.

3. 3

   Integrate into a Server Action form (optional)

   For forms that use Server Actions, add a validateVat server action in actions/vat.ts marked with 'use server'. Accept FormData, extract vatNumber, call the TaxID API directly (server-side), and return the result. Invoke with useActionState in the Client Component. This replaces the API route approach and is cleaner for progressive-enhancement forms.

4. 4

   Server Component: pre-fill billing from stored VAT

   In a Server Component (no 'use client' directive), you can fetch VAT validation data directly on render. Read the customer's stored vatNumber from your database, call the TaxID API to get the latest status, and pass the result as props to the billing form Client Component. This pattern is useful for billing settings pages where you want to show the current validation status without a client-side API call on load.

5. 5

   Webhook handler for subscription re-validation

   Add app/api/webhooks/stripe/route.ts. On invoice.upcoming events, read the Stripe customer's vat_number metadata, call the TaxID API, and if the status has changed (e.g., went from active to inactive), update the customer's tax_exempt flag in Stripe and notify your finance team via email or Slack. Log every validation with request_id for audit.

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