SIGNALS Docs
Exit Reader View
100%
Theme

Reader View

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_validated fires 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