UK VAT ID Validator

Out of the box, Craft Commerce supports basic formatting validation for VAT IDs in the European Union. This plugin provides additional checks to ensure tax rules are correctly applied for customers with UK VAT IDs:

• Tax rules are given a setting that allows merchants to disqualify taxes when a valid UK Tax ID (VAT number) is provided during checkout;
• UK Tax IDs are validated directly with HMRC’s official API;

How it Works

Enabling the validateBusinessTaxIdAsVatId in Craft Commerce 4.8 (globally) or Validate Business Tax ID as VAT ID in Craft Commerce 5.x (in one or more stores) tells Commerce to perform cursory validation of the Organization Tax ID field on addresses used for tax calculation. This functionality is available to all Commerce installations.

As tax rules are evaluated in the process of calculating order totals, UK VAT ID Validator ensures the provided VAT ID is both correctly formatted and actually exists, using the HMRC API.

Note

Make sure your useBillingAddressForTax config setting (Commerce 4.8) or Use Billing Address For Tax store setting (Commerce 5.x) agrees with how you want to handle taxes in each market!

Requirements

• Craft CMS 4.x or 5.x
• Craft Commerce 4.8 or 5.3 and later
• HMRC credentials for Version 2 of the HMRC VAT API

Installation

You can install this plugin from the Plugin Store or with Composer. Once installed, follow the configuration instructions!

From the Plugin Store

Go to the Plugin Store in your project’s control panel and search for “UK VAT ID Validator.” On the plugin’s page, press Install.

With Composer

Open your terminal and run the following commands:

# Go to the project directory:
cd /path/to/my-project

# Require the plugin package with Composer:
ddev composer require craftcms/commerce-uk-vat-id-validator

# Tell Craft to install the plugin:
ddev craft plugin/install uk-vat-id-validator

Configuration

Step 1: Configure Plugin Settings

Navigate to Settings → UK Tax ID Validator in the control panel, and fill in the following fields:

• HMRC Client ID: Obtain this from the HMRC Developer Hub.
• HMRC Client Secret: Provided alongside your HMRC Client ID.
• Sandbox Mode: Enable for testing (disables live API calls).

Warning

Whenever possible, use an environment variable so that these secrets don’t leak into your project config files!

Optional Step 2: Enable Validation on Tax Rates

• Navigate to Commerce → Tax Rates.
• Edit a tax rate and check UK VAT ID under the Disqualify with valid business tax ID? option.
• Save the tax rate.

When a valid UK tax ID is provided in the address, the tax will not be applied.

Support

Please report any issues on GitHub. Need help or have a question? Email us at [email protected].

🍋