Home / Use cases / WooCommerce

WooCommerce Spain NIF/CIF validation

Validate Spanish NIF and CIF numbers in WooCommerce checkout. Automatically apply B2B tax exemptions for verified Spanish businesses and autonomos.

Implementation steps

1. 1

   Add NIF/CIF field to checkout

   Use the woocommerce_checkout_fields filter to inject a custom 'billing_nif' field into the billing section. Set it as required for customers selecting Spain as their billing country by combining the filter with a conditional on billing_country === 'ES', so domestic buyers are always prompted while foreign buyers are not.

2. 2

   Validate via TaxID API on save

   Hook into woocommerce_checkout_process to call GET /api/v1/validate/ES/:nif server-side before order creation. If status is 'active', store the company_name in order meta; if 'invalid', call wc_add_notice() with type 'error' to surface the failure inline; if 'service_unavailable', allow checkout but flag the order with a custom meta key (e.g. _vat_pending_verification: 1) for asynchronous re-validation.

3. 3

   Display validation status to customer

   After the API call, render inline feedback using JavaScript and the WooCommerce checkout block's update_checkout event: show a green company name confirmation for valid numbers, a red 'VAT number not found in VIES' message for invalid ones, and a neutral 'Validation service temporarily unavailable' notice for service_unavailable responses, so the buyer understands why checkout proceeds without exemption.

4. 4

   Auto-apply B2B pricing rules

   On successful validation, use the woocommerce_customer_taxable_class filter to return 'zero-rate' for the order, and assign the customer role 'b2b-verified' via wp_update_user. The zero-rate tax class suppresses WooCommerce's VAT calculation, and the role gates access to wholesale price lists or catalog discounts configured via WooCommerce Product Tables or a role-based pricing plugin.

Code example

const res = await fetch(
  'http://localhost:3000/api/v1/validate/DE/ESA12345678',
  { 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/ESA12345678",
    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