SIGNALS Docs

Tax setup

Tax zones, tax categories, item tax codes and customer tax profiles, tax rates and tax rules in Admin → Money & Pricing.

Overview

The tax screens under Admin → Money & Pricing hold the reference data the tax engine uses. Each screen has its own section on this page, in the same order as the admin sidebar.

Screen Route What it holds
Tax Zones /admin/settings/tax/zones Geographic zones used for cross-border tax rule matching
Tax Categories /admin/settings/tax/categories Catalogue item tax category classes (standard, reduced, zero, exempt)
Item Tax Codes /admin/settings/tax/item-tax-codes Per-line tax codes for catalogue items
Customer Tax Profiles /admin/settings/tax/customer-tax-profiles Tax profiles for accounts
Tax Rates /admin/settings/tax/rates Named percentages referenced by tax rules
Exchange Rates /admin/settings/exchange-rates Currency conversion rates (documented on its own page)
Tax Rules /admin/settings/tax/rules Class rules and zone rules that resolve to a rate or treatment

For how these pieces combine at calculation time (zone-aware resolution, buyer types, reverse charge and VAT validation), see Tax & Compliance. Finance-wide tax settings, such as the tax rate selection date and the reverse charge label, are on Finance settings.

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

The screens open for users with settings.view. Creating, editing and deleting tax zones, categories, types, rates and rules requires tax-types.manage.

Tax zones

Tax zones are geographic scopes used by zone-aware tax rules: buyer types and the reverse charge, zero-rated, exempt and outside-scope treatments.

List columns: Name, Slug, Countries (account-country count), Priority, Status. The list is sorted by priority, highest first.

Form fields: Name, Slug, Description, Priority, Active.

Click Add Tax Zone to create a zone. Edit or delete a zone from its row.

Tax categories

Tax categories classify catalogue items by tax treatment for zone rules.

List columns: Name, Slug, Type, Default, Status. Filter the list by name.

Form fields: Name, Slug, Type (Standard, Reduced, Zero rated or Exempt), Description, Default category, Active.

Click Add Tax Category to create a category. Edit or delete a category from its row.

Item tax codes

Item tax codes classify catalogue items for class-based tax resolution, for example "Standard Rate", "Reduced Rate", "Zero Rated" or "Exempt". Surcharges also carry an item tax code.

List columns: Name, Description, Default.

Form fields: Name, Description, Default item tax code.

Action What it does
Add item tax code Create a type
Edit Change the name, description or default flag
Set default Make this the default for new catalogue items; the preceding default is cleared
Delete Remove the type. The default type cannot be deleted

Customer tax profiles

Customer tax profiles classify accounts for class-based tax resolution, for example "Standard", "Tax Exempt", "Reverse Charge" or "Charity". Assign them on the account form in the Tax & Pricing section (Customer tax profile and Supplier tax profile).

List columns: Name, Description, Default.

Form fields: Name, Description, Default customer tax profile.

The actions match item tax codes: add, edit, set the default for new companies, and delete any type that is not the default.

Tax rates

Tax rates are named percentages, for example "UK Standard" at 20%, "Reduced" at 5% and "Zero" at 0%. Tax rules reference rates; rates are not applied to catalogue items directly.

List columns: Name, Description, Rate, Status.

Form fields: Name, Description, Rate (%), Active.

Deleting a rate is blocked while any tax rule references it, including inactive rules. The API returns 422 with code tax_rate_in_use, and the rate and its rules stay unchanged.

Deleting is also blocked while any invoice tax or credit note tax references the rate, through the app, the API and MCP. The API returns 422 with code tax_rate_referenced_by_documents before any deletion, audit event or webhook. Historical tax values and their rate links stay unchanged. To retire a rate that documents still use, turn off Active (is_active: false) instead.

Tax rules

The Tax Rules list combines two kinds of rule, ordered by priority (highest first):

  • Class rules map a customer tax profile and an item tax code to a tax rate. Click Add Class Rule and set the customer tax profile, item tax code, tax rate, priority and active flag.
  • Zone rules match a seller zone and buyer zone to a treatment. Click Add Zone Rule and set the seller zone, buyer zone, optional buyer type, whether a validated tax ID is required, the tax category, the result type (Standard, Reverse charge, Zero rated, Exempt or Outside scope), legal text, priority and active flag.

List columns: Type, Name / Mapping, Zones, Buyer, Result, Priority, Status.

When more than one tax code rule could apply, the rule with the highest priority wins. If no rule matches, no tax is applied. Each rule can be deactivated without deleting it. The legal text on a zone rule appears on totals and documents when the rule applies a reverse charge.

The configured default item tax code cannot be deleted. Select a replacement first; DELETE /api/v1/item_tax_codes/{itemTaxCode} returns 422 while that code remains the default.