> ## Documentation Index > Fetch the complete documentation index at: https://zenskar.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Tax rates ## Tax rates This document explains what tax rates are, how Zenskar matches a jurisdiction, how tax components and rate changes work, and the limits of the Zenskar tax engine. > **Map of concepts** > > | Concept | Details | > | - | - | > | [Tax rate](#tax-rates-what-the-zenskar-tax-engine-applies) | A tax rate belongs to one tax category and one jurisdiction, in one business entity. | > | [Jurisdiction](#jurisdictions) | A tax rate applies to one jurisdiction. | > | [Tax component](#tax-components) | A rate change has one or more tax components. | > | [Rate change](#rate-changes) | A tax rate has one or more rate changes, each for a period of time. | > > A tax rate belongs to one tax category and one jurisdiction in a business entity. Zenskar matches the most specific jurisdiction to the billing address of the customer and applies only that tax rate. The tax components of the rate change that is in effect add up to the total percentage. > **Related modules** > > Tax rates use the following modules: > > | Module | Details | > | - | - | > | [Tax configuration](/docs/20260301/product-modules/settings/tax-configuration/concepts/tax-configuration) | Each tax rate belongs to a tax category and to a served country of a business entity. | > > The following modules use tax rates: > > | Module | Details | > | - | - | > | [Contracts](/docs/20260301/product-modules/contracts/concepts/contracts) | A contract uses the tax rates of its business entity when the business entity uses the Zenskar tax engine for the served country of the customer. | ## Tax rates: what the Zenskar tax engine applies A **tax rate** is the set of percentages that the Zenskar [tax engine](/docs/20260301/product-modules/settings/glossary#tax-engine) applies to one [tax category](/docs/20260301/product-modules/settings/glossary#tax-category) in one jurisdiction. Each [business entity](/docs/20260301/product-modules/settings/glossary#business-entity) configures its own tax rates. The percentages of a tax rate can change over time. Each change is a rate change. A tax rate needs a [served country](/docs/20260301/product-modules/settings/glossary#served-country). **Add Tax Rate** is unavailable until the business entity has a served country. The **Country** list shows only served countries. ## Jurisdictions A **jurisdiction** is the geographic area that a tax rate covers. A jurisdiction is defined by one or more geographic levels. Each level narrows the level above it. | Level | Required | Requires | | - | - | - | | Country | Yes | A served country of the business entity | | State | No | Country | | City | No | State | | ZIP-code range | No | State and city | Zenskar rejects a city without a state, and a ZIP-code range without a state and a city. The start code and the end code of a ZIP-code range must have the same length. The start code must be less than or equal to the end code. A single ZIP code is a range whose start code and end code are the same. ### How Zenskar matches a jurisdiction Zenskar matches tax rates against the default billing address of the customer. Zenskar starts at the most specific level in the address and moves up one level at a time, in this order: 1. ZIP code 2. City 3. State 4. Country Zenskar uses the first level that has a matching tax rate. It applies only that tax rate. Tax rates of different jurisdictions are not added together. A state tax and a city tax that both apply belong together, as tax components of the city-level tax rate. At each level, a tax rate matches as follows: | Level | A tax rate matches when | | - | - | | ZIP-code range | The ZIP code of the address has the same length as the range codes and falls within the range. Zenskar ignores the state and city of the tax rate. | | City | The city of the tax rate equals the city of the address. If the address has a state, the state of the tax rate must also equal it. | | State | The state of the tax rate equals the state of the address. The tax rate has no city. | | Country | The tax rate has no state, city, or ZIP-code range. | A jurisdiction matches only when its state, city, and ZIP code are the same as in the billing address of the customer. Zenskar moves only from a more specific level to a less specific one. Zenskar matches only at levels that the address has. For example, a state-level tax rate does not match an address without a state. #### Example: tax-rate applicability based on billing address A business entity serves the United States with the Zenskar tax engine. It has the following tax rates for one tax category. It has no country-level tax rate for the United States. | Tax rate | Jurisdiction | Tax components | Total | | - | - | - | - | | 1 | State `CA` | State tax 6% | 6% | | 2 | State `CA`, city `San Francisco` | State tax 6%, city tax 2.5% | 8.5% | | 3 | State `CA`, city `San Francisco`, ZIP-code range `94105` to `94107` | State tax 6%, city tax 2.5%, district tax 0.5% | 9% | Tax rate 2 and tax rate 3 repeat the state tax as a tax component. The Zenskar tax engine applies only one tax rate. Each tax rate must therefore include every tax that applies in its jurisdiction. The following table shows which tax rate applies to customers with different billing addresses: | Customer billing address | ZIP-code level | City level | State level | Country level | Result | | - | - | - | - | - | - | | `CA`, `San Francisco`, `94105` | Tax rate 3 matches. | Not checked | Not checked | Not checked | 9% | | `CA`, `San Francisco`, `94110` | No match. `94110` is outside the range. | Tax rate 2 matches. | Not checked | Not checked | 8.5% | | `CA`, `Los Angeles`, `90012` | No match | No match. No tax rate exists for `Los Angeles`. | Tax rate 1 matches. | Not checked | 6% | | `CA`, `San Francisco`, `94105-1234` | No match. The ZIP code has 10 characters, and the range codes have 5. | Tax rate 2 matches. | Not checked | Not checked | 8.5% | | `California`, `San Francisco`, no ZIP code | Skipped. The address has no ZIP code. | No match. The state `California` does not equal `CA`. | No match. The state `California` does not equal `CA`. | No match. No country-level tax rate exists. | No tax rate | | `TX`, `Austin`, `78701` | No match | No match | No match | No match. No country-level tax rate exists. | No tax rate | The fourth and fifth rows show common mistakes. A ZIP+4 code falls back to a less specific tax rate. A state name that differs from the state of the tax rate matches nothing. When no tax rate matches, the Zenskar tax engine has no tax rate to apply. This can affect [contracts](/docs/20260301/product-modules/contracts/concepts/contracts) for that customer. The tax rates in this example are fictional. They do not reflect the tax law of any state or city. ## Tax components A **tax component** is a named percentage within a rate change. A rate change has one or more tax components. Each tax component has a **Tax Name**, for example `GST`, and a **Tax Percentage**. The name must be unique within the rate change. The panel notes that the tax name is displayed on invoices. The Zenskar tax engine adds the tax components of a rate change together. For example, a rate change with `CGST` at 9% and `SGST` at 9% applies 18%. Compound rates, in which one tax component applies to an amount that includes another, are not supported. ## Rate changes A **rate change** is one dated entry of a tax rate. A tax rate is a sequence of rate changes. Each rate change has a start date and its own tax components. A rate change applies until the next rate change starts. When a tax rate is added, several rate changes can be added at once with **Schedule Rate Change**. Zenskar sets the end date of each rate change to the day before the next one starts. The last rate change has no end date. Rate changes of a tax rate cannot share a start date, and cannot overlap or share a day. Zenskar rejects a rate change that breaks either condition. If saving several rate changes fails partway, the rate changes saved before the failure stay saved. Zenskar reports how many rate changes it saved. The remaining rate changes stay in the panel, ready to fix and save again. > [!NOTE] > > A saved rate change cannot be edited, ended, or deleted in the dashboard. After a rate change without an end date is saved, no later rate change can be added for the same tax category and jurisdiction. Known future changes, such as an announced rate increase, belong in the tax rate when it is added. A new rate change applies from its start date. A new rate change can affect active [contracts](/docs/20260301/product-modules/contracts/concepts/contracts) that use the tax category. Each rate change has one of the following statuses: | Status | Meaning | | - | - | | **Active** | The rate change has started, has not ended, and is the latest rate change of the tax rate to start. | | **Scheduled** | The start date of the rate change is in the future. | | **Expired** | The rate change has ended, or a later rate change has replaced it. | The tax rates list shows the number of rate changes of each tax rate. The number opens **Tax Rate Details**, which lists every rate change with its start date, end date, and tax components. ### Example: tax-rate changes over time A business entity serves Australia with the Zenskar tax engine. GST on SaaS subscriptions was 9% in 2025. It is 10% from 1 January 2026. An increase to 11% is announced for 1 July 2027. The tax rate for the tax category `SaaS subscription` in Australia has three rate changes: | Rate change | Tax components | Start date | End date | Status on 1 March 2027 | | - | - | - | - | - | | 1 | GST 9% | 1 January 2025 | 31 December 2025 | **Expired** | | 2 | GST 10% | 1 January 2026 | 30 June 2027 | **Active** | | 3 | GST 11% | 1 July 2027 | None | **Scheduled** | Zenskar set the end dates of rate changes 1 and 2 when the three rate changes were saved together. On 1 July 2027, rate change 3 becomes **Active**. Rate change 2 then becomes **Expired**. If only rate changes 1 and 2 had been saved, rate change 2 would have no end date. Rate change 3 would then overlap it, and the dashboard could not add it. For this reason, the announced increase belongs in the tax rate when it is added. The percentages in this example are fictional. ### Expired rate changes: why Zenskar keeps them Zenskar keeps every rate change after it expires. A rate change cannot be deleted in the dashboard. Tax for a billing period uses one rate change: the one in effect on a single date of that period. It is not the rate change in effect today. Zenskar does not split a billing period across two rate changes. Which date applies depends on the billing of the [contract](/docs/20260301/product-modules/contracts/concepts/contracts). In the example, tax for 2025 uses GST 9% from rate change 1, which is already **Expired**. Tax for March 2027 uses GST 10%, even when Zenskar calculates it after 1 July 2027. The following cases use the rate changes from the example: | Rate change | GST | In effect | | - | - | - | | 1 | 9% | All of 2025 (now **Expired**) | | 2 | 10% | 1 January 2026 to 30 June 2027 | | 3 | 11% | From 1 July 2027 | Expired rate changes help in the following cases: | Case | How expired rate changes help | Example | | - | - | - | | An invoice covers a past period. | Tax for the period uses the rate change in effect on the date of the period. | A contract created in 2027 starts on 1 June 2025. Its invoices for 2025 use GST 9% from rate change 1. | | An invoice for a past period is generated again. | The new invoice uses the same rate change as the original period. | An invoice for March 2027 is generated again in August 2027. It uses GST 10% from rate change 2. | | Zenskar checks the tax of an invoice again before approval. | The check uses the date of each line of the invoice. | An invoice for June 2027 is approved in July 2027. The check uses GST 10% from rate change 2. | | An auditor asks which rate applied in a period. | The expired rate change records the percentages and the dates. | The rate for 2025 was GST 9%, as rate change 1 shows. | Deleting an expired rate change would leave those periods without the correct rate. This can affect [contracts](/docs/20260301/product-modules/contracts/concepts/contracts) and invoices for those periods. ## Limits of the Zenskar tax engine The Zenskar tax engine applies only the tax components that are configured. It does not apply tax rules such as reverse charge, place-of-supply rules, or nexus thresholds. It does not update tax rates when tax authorities change them. The organization maintains every tax rate. A third-party tax engine can apply these tax rules and maintain tax rates on behalf of the organization. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.