Tax & Compliance
EU/UK tax zones, buyer types, zone-aware resolution, VIES validation, and finance settings.
Overview
The tax engine supports zone-aware resolution for EU/UK compliance. Tax is resolved per document context — rentals, invoices, credit notes, and purchase orders — through ZoneAwareTaxResolver and DocumentTaxBreakdown extraction.
The tax code rule matrix (customer tax profile + item tax code → rate) remains for reference data; see Tax profiles, item tax codes and the rate matrix. Zone rules take precedence for financial documents in configured territories.
Tax zones
Tax zones group countries and regions with zone-specific rules. Each zone defines how buyer type and catalogue item tax category combine to produce a treatment.
| Admin route | Purpose |
|---|---|
/admin/settings/tax/zones |
List zones |
/admin/settings/tax/zones/create |
Create zone |
/admin/settings/tax/zones/{taxZone}/edit |
Edit zone rules |
See Tax Zones API.
Buyer types
Four buyer types drive zone resolution:
| Type | Typical use |
|---|---|
| Business | B2B with VAT number |
| Individual | B2C consumer |
| Government | Public sector |
| Charity | Registered charity |
Buyer type is set on the account and consumed at document resolution time. Fresh installs seed reachable zone rules for each type.
Resolution outcomes
ZoneAwareTaxResolver returns treatments including:
| Treatment | Description |
|---|---|
| Standard rated | Normal VAT on net amount |
| Reverse charge | Customer accounts for VAT; legal text on documents |
| Zero-rated | 0% rated supply |
| Exempt | Exempt from VAT |
| Outside scope | Not title to VAT |
Reverse charge eligibility can depend on VIES VAT validation (see below). The reverse-charge display label is configurable under Finance settings.
Catalogue item tax category
Catalogue items carry a tax category dimension end-to-end on line items and documents. Surcharges also reference per-surcharge item tax codes. See Tax profiles, item tax codes and the rate matrix for the underlying tax code definitions.
VAT validation
Signals validates VAT numbers asynchronously. Supported EU prefixes (including XI for Northern Ireland) are checked against VIES; GB/UK numbers receive only a local mod-97 checksum check. Other prefixes are marked invalid. No VAT number is checked against HMRC.
- Validation runs after VAT number entry or manual confirmation
- Results feed reverse-charge eligibility on the account
- 30-day revalidation with a scheduled expiry check job
- Webhook:
account.vat_validatedfires after VIES or manual confirmation
Document axes
| Document | Tax axis |
|---|---|
| Rental | Live resolution on lines; frozen at checkout |
| Invoice | Frozen snapshot from checkout |
| Credit note | Negated mirror of invoice tax |
| Purchase order | Purchase-axis tax for sub-hire procurement |
Tax profiles, item tax codes and the rate matrix
Customer tax profiles classify accounts for the rate matrix; supplier tax profiles use the same definitions on purchases.
Item tax codes classify catalogue items and surcharges for the rate matrix, while tax categories select zone-based treatments.
The two matrix axes work together:
- Item tax codes classify items by tax treatment, for example "Standard Rate", "Reduced Rate", "Zero Rated" or "Exempt". One code is the default for new catalogue items. Surcharge lines also carry an item tax code.
- Customer tax profiles classify accounts by tax status, for example "Standard", "Tax Exempt", "Reverse Charge" or "Charity". One profile is the default for new companies, and accounts pick theirs on the account form.
Tax rates are named percentages, and tax code rules map a customer tax profile and an item tax code to a rate with a priority. When calculating tax on a line, Signals takes the item's tax code and the account's customer tax profile, resolves the highest-priority active tax code rule for that pair, and applies its rate. If no rule matches, no tax is applied.
The screens for all of these are described in Tax setup. The same resources are available through the API reference.
Using it in the app
Tax admin lives under Admin → Money & Pricing (sidebar group tax, gated on tax-types.view, rates.view, or pricing.view for the Money & Pricing nav link). Mutations on tax types, rates, rules, zones, and categories go through action classes that require tax-types.manage.
The tax zones, tax categories, item tax codes and customer tax profiles, tax rates and tax rules screens — their routes, list columns, form fields and actions — are described in Tax setup.
Finance settings
Route: /admin/settings/finance
| Section | Fields |
|---|---|
| Tax rate selection date (shown as Tax Rate Date) | Supply date or Invoice date selects the rate, not the legal tax point; the legal tax point and reporting period remain the invoice issue date |
| Pricing Defaults | New rentals default to prices include tax; Show tax breakdown on documents |
| VAT Validation | VAT validation validity (days) — how long a VIES result or GB/UK local checksum check remains trusted; no HMRC check is performed |
| Reverse Charge Display | Reverse charge label — text shown on tax breakdowns and documents when reverse charge applies |
| Pricing rounding | Rounding direction (half up or bankers) and maximum line discount percent |
| Zone resolution | Unresolved zone fallback (seller domestic zone) and the default item tax code |
Write-off ceilings, portal payments, account credit-check settings and the billing-run undo window are also on this page; see Finance settings.
Click Save Changes to persist. There is no dedicated tax-configuration audit trail — changes surface in the general Action Log when auditable events fire.
Account tax fields
On the account form (companies and venues), the Account section shows Tax Number with validation badges:
| Badge | Meaning |
|---|---|
| Pending validation | VAT number entered, check not yet complete |
| Valid | Passed VIES validation for a supported EU prefix, or the local checksum for GB/UK; not HMRC validation |
| Invalid | Validation failed |
Re-check VAT (accounts.edit) re-queues validation.
The Tax & Pricing section also exposes Customer tax profile and Supplier tax profile (class axis). Fields for tax zone, buyer type, and tax exempt exist on the account model but are not on the account form UI yet — zone resolution uses account country and company data at runtime.
Warehouse seller zone
Warehouses are managed at /admin/settings/warehouses (Admin → Setup). The form covers name, address, country, currency and timezone — there is no Tax Zone picker. The seller zone for documents is resolved at runtime from the warehouse's stored tax zone when set, otherwise from its country. See Warehouses.
Reverse charge in documents
When zone resolution returns reverse charge, totals and generated documents show the reverse charge label from Finance settings plus any legal text configured on the zone rule. No separate reverse-charge editor exists outside those admin screens.
Permissions summary
| Permission | UI effect |
|---|---|
tax-types.view |
Tax admin sidebar link |
tax-types.manage |
Create / edit / delete tax types, rates, rules, zones, categories |
accounts.edit |
Re-check VAT on account form |
Related documentation
- Multi-Currency & Tax — currencies, exchange rates, base engine
- Tax setup — the tax zones, categories, types, rates and rules screens
- Invoicing — frozen tax at checkout
- Sub-Hire & Procurement — PO tax axis