Tax & Compliance

EU/UK tax zones, buyer types, zone-aware resolution, VIES validation, and finance settings.

Overview#

Phase 4 extends the Phase 2 tax engine with 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 legacy rule matrix (company class + catalogue item class → rate) remains for reference data; see Tax types. 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.

See Tax Zones API.

Buyer types#

Four buyer types drive zone resolution:

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:

Reverse charge eligibility can depend on VIES VAT validation (see below). The reverse-charge display label is configurable under Finance settings.

CatalogueItem tax category#

CatalogueItems carry a tax category dimension end-to-end on line items and documents. Surcharges also reference per-surcharge tax types. See Tax types for the underlying class definitions.

VIES VAT validation#

For EU B2B reverse charge, Signals validates VAT numbers asynchronously against VIES:

• 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_validated fires after VIES or manual confirmation

Finance settings#

Route: /admin/settings/finance

Tax configuration changes are recorded in the tax configuration audit trail.

Document axes#

Using it in the app#

Tax admin lives under Admin → Tax (sidebar group tax, gated on tax-types.view for the Tax nav link). Mutations on tax types, rates, rules, zones, and categories go through action classes that require tax-types.manage.

Tax Zones and Tax Categories are in the admin sidebar but not on the admin landing overview cards (those cards list Finance, legacy classes, rates, and rules only).

Finance settings#

Route: /admin/settings/finance

Click Save Changes to persist. There is no dedicated tax-configuration audit UI — changes surface in the general Action Log when auditable events fire.

Tax zones, categories, and rules#

Tax Zones — list shows Name, Slug, Countries (account-country count), Priority, Status. Form fields: Name, Slug, Description, Priority, Active.

Tax Categories — list shows Name, Slug, Type, Default, Status. Form: Name, Slug, Type (Standard / Reduced / Zero rated / Exempt), Description, Default category, Active.

Tax Rules index combines legacy Class rules and Zone rules in one table (Type, Name/Mapping, Zones, Buyer, Result, Priority, Status).

• Add Class Rule — company tax type + catalogue item tax type → tax rate, priority, active
• Add Zone Rule — seller zone, buyer zone, optional buyer type, requires validated tax ID, tax category, result type (Standard / Reverse charge / Zero rated / Exempt / Outside scope), legal text, priority, active

Reverse-charge legal text on zone rules feeds document and totals rendering; the configurable display label comes from Finance settings.

Account tax fields#

On the account form (companies and venues), the Account section shows Tax Number with validation badges:

Re-check VAT (accounts.edit) re-queues validation.

The Tax & Pricing section also exposes Sale Tax type and Purchase Tax type (legacy 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 and address only — there is no Tax Zone picker on the warehouse modal. Seller zone for documents is resolved from each warehousee's country/tax_zone_id at runtime via TaxZoneResolver.

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#

Related documentation#

• Multi-Currency & Tax — currencies, exchange rates, base engine
• Tax types — catalogue item/company classes and rule matrix
• Invoicing — frozen tax at checkout
• Sub-Hire & Procurement — PO tax axis