Home / Use cases / Shopify

UK VAT validation in Shopify B2B

Validate UK VAT numbers for B2B customers in Shopify. Required under UK Making Tax Digital rules for businesses selling cross-border to UK companies.

Implementation steps

1. 1

   Add VAT number field to billing address

   Use a Shopify Checkout UI Extension or a custom storefront to add a 'UK VAT number' input to the billing address step. Persist the value in a customer metafield (namespace: 'tax', key: 'vat_number') so it is available to webhooks and future orders without asking again.

2. 2

   Validate on order creation via webhook

   Subscribe to the orders/create webhook in your Shopify Partner app. When it fires, read the vat_number metafield, call GET /api/v1/validate/GB/:vatNumber, and handle the three possible status values: 'active' proceeds to exemption, 'invalid' triggers a follow-up email to the customer, and 'service_unavailable' queues a retry job to avoid incorrectly exempting an unverified number.

3. 3

   Tag customer as B2B if valid

   On a valid response, use the Shopify Admin REST API (PUT /admin/api/2024-01/customers/:id.json) or GraphQL mutation to add the tag 'b2b-verified' to the customer. This tag can drive Shopify discount scripts, price list assignments, and B2B metafield visibility without re-querying the VAT status on every session.

4. 4

   Apply tax exemption

   Update the customer object with tax_exempt: true via the Shopify Admin API to suppress VAT on subsequent orders. Store the validated VAT number, the company_name from the TaxID response, and the validation date in customer metafields for Making Tax Digital record-keeping; HMRC requires you to retain evidence of VAT validation for at least six years.

Code example

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