Tax Configuration

Tax configuration in NexusRMS supports a wide range of international tax regimes, from UK VAT to Australian GST to US sales tax. Each tax rate can be targeted by geographic region and item type, with compound and inclusive calculation modes, effective date ranges, and direct mapping to external accounting platforms.

Tax types

NexusRMS defines nine tax types through the TAX_TYPES constant. When creating a tax rate, select the type that matches your jurisdiction:

1. vat — Value Added Tax (VAT): used in the UK, EU, and many other countries
2. gst — Goods & Services Tax (GST): used in Australia, New Zealand, India, and others
3. sales_tax — Sales Tax: used in the United States and some other jurisdictions
4. pst — Provincial Sales Tax (PST): used in certain Canadian provinces
5. hst — Harmonized Sales Tax (HST): used in Canadian provinces that combine federal and provincial taxes
6. service_tax — Service Tax: applied specifically to service charges in some jurisdictions
7. withholding_tax — Withholding Tax: deducted at source before payment reaches the supplier
8. customs_duty — Customs Duty: applied to imported goods
9. other — Other: for any tax type not covered by the above categories

Creating a tax rate

Navigate to Configuration > Financial Settings > Invoice Settings and locate the tax rate configuration, or manage tax rates through the API. The form fields are:

• Name (required) — Descriptive label (e.g., "VAT Standard Rate", "Zero Rate", "Reduced Rate")
• Code (required) — Short unique identifier (e.g., VAT20, GST10, ZERO)
• Tax Type (required) — One of the nine types listed above
• Rate (required) — Tax percentage (e.g., 20.00 for 20%). Stored with two decimal places.
• Description — Additional context for the tax rate
• Tax Number — Your tax registration number (e.g., VAT registration number), displayed on invoices and quotes
• Notes — Internal notes for staff reference
• Default — Toggle to mark this as the default tax rate for new documents. Only one tax rate can be the default at a time.
• Active — Toggle to control whether this rate appears in selection lists
• Display Order — Numeric value controlling sort position in dropdown menus

Compound and inclusive tax

Two boolean fields control how the tax rate is calculated:

• is_compound — When enabled, tax is calculated on the subtotal plus any other taxes already applied (tax stacking). This is used in jurisdictions where multiple taxes are layered on top of each other (e.g., Canadian GST + PST on the GST-inclusive amount).
• is_inclusive — When enabled, the displayed price already includes tax. The calculateTax(subtotal) method extracts the tax portion from the inclusive price rather than adding it on top. This is common in consumer-facing pricing in the UK and EU.

Geographic targeting

Tax rates can be scoped to specific regions to ensure the correct rate is applied based on the client's location:

• country_code — ISO 3166-1 alpha-2 country code (e.g., GB, US, AU). If set, this tax rate only applies to transactions in the specified country.
• region_code — State, province, or region code (e.g., CA for California, ON for Ontario). Used for sub-national tax variations.
• applicable_regions — JSON array of region codes where this tax rate applies. If null, the rate applies everywhere.

The appliesInRegion(regionCode) method checks whether a tax rate applies in a given region. The forCountry() and forRegion() scopes filter tax rates by geographic criteria.

Category targeting

Tax rates can be configured to apply only to specific types of line items. Four boolean fields control this:

• applies_to_equipment — Tax applies to equipment hire charges
• applies_to_labor — Tax applies to labour and crew charges
• applies_to_delivery — Tax applies to delivery and transport charges
• applies_to_services — Tax applies to general service charges

Use the appliesTo(itemType) method to check whether a tax rate applies to a specific item type. Pass one of the four values: equipment, labor, delivery, or services.

Effective dates

Tax rates can have a defined validity period to handle rate changes over time:

• effective_from — The date from which this tax rate is valid. If null, the rate is valid from the creation date.
• effective_to — The date after which this tax rate expires. If null, the rate has no expiry.
• isEffective() — Returns true if the rate is active, the current date is after effective_from, and the current date is before effective_to
• hasExpired() — Returns true if the effective_to date has passed

The effective() scope filters to only currently valid tax rates, combining the active, effective_from, and effective_to checks. When a tax rate changes (e.g., a VAT rate increase), create a new rate with the updated percentage and an effective_from date, then set effective_to on the old rate.

Calculation methods

The TaxRate model provides two calculation methods:

• calculateTax(subtotal) — Returns the tax amount for a given subtotal. For inclusive tax, this extracts the tax portion from the price. For exclusive tax, it calculates the additional tax to add.
• calculateTotal(subtotal) — Returns the subtotal plus tax. For inclusive tax, this returns the original subtotal unchanged since tax is already included.

The getFormattedRate() method returns the rate as a formatted string (e.g., "20.00%"), and getTaxTypeName() returns the human-readable type label.

External system mapping

For integration with accounting platforms such as Xero, QuickBooks Online, and Sage, each tax rate has:

• external_id — The tax code identifier in the external accounting system
• external_mapping — JSON object containing platform-specific mapping data for synchronisation

These fields ensure that when invoices and payments are synced to your accounting software, the correct tax code is applied automatically.

Client-level tax overrides

Individual clients can have tax-specific settings on their client record:

• tax_rate_override — Overrides the default tax rate for this client (e.g., a client in a zero-rated jurisdiction)
• tax_exempt — Marks the client as tax-exempt, applying a 0% rate regardless of the document or tenant default

Tips

• Set your default tax rate first — Mark your most commonly used rate as the default so it is pre-selected on new quotes and invoices.
• Use effective dates for rate changes — When a tax rate changes, create the new rate with an effective_from date and set effective_to on the old rate, rather than editing the existing rate. This preserves historical accuracy on past documents.
• Enable category targeting for mixed invoices — If your jurisdiction taxes equipment differently from labour, create separate tax rates with the appropriate applies_to flags to ensure correct line-item taxation.
• Map to your accounting platform early — Set up external_id and external_mapping when creating tax rates to ensure seamless synchronisation from the start.
• Use tax-exempt for qualifying clients — Rather than manually setting 0% tax on every document, mark the client as tax_exempt on their record to automate zero-rating.
• Enter your tax number — The tax_number field is printed on invoices and quotes. Ensure it is set correctly for legal compliance.