> ## 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.

# How-to guides

## Prerequisites

Every task on this page needs a role with the **Can Update Organisation Config** permission. Users without it can view tax configuration, but Zenskar rejects their changes. For details, see [Permissions](/docs/20260301/product-modules/settings/tax-configuration/reference#permissions).

## Manage tax categories

### Create a tax category

A [tax category](/docs/20260301/product-modules/settings/glossary#tax-category) classifies [products](/docs/20260301/product-modules/products/glossary#product) by how they are taxed. Every [business entity](/docs/20260301/product-modules/settings/glossary#business-entity) in your organization uses the same tax categories.

> [!CAUTION]
>
> You cannot delete a tax category after you create it. To retire a tax category, rename it.

1. Go to **Settings** > **Tax Configuration**.
2. On the **Tax Categories** tab, click **Add Tax Category**.
3. In **Tax Category Name**, enter a name that is unique in your organization.
4. Optional: under **Third-Party Tax Tool Mapping**, enter or select a [third-party tax code](/docs/20260301/product-modules/settings/glossary#third-party-tax-code) for each connected third-party tax engine.
5. Click **Add Tax Category**.

Zenskar confirms the change. For how tax categories work, see [Tax categories](/docs/20260301/product-modules/settings/tax-configuration/concepts/tax-configuration#tax-categories-how-products-are-taxed).

### Rename a tax category

[Tax rates](/docs/20260301/product-modules/settings/glossary#tax-rate) and other modules keep using a tax category after you rename it.

1. Go to **Settings** > **Tax Configuration**.
2. On the **Tax Categories** tab, open the menu of the tax category, and click **Edit**.
3. In **Tax Category Name**, enter the new name.
4. Click **Save Changes**.

Zenskar confirms the change.

### Map a tax category to a third-party tax code

A third-party tax code applies in every business entity that uses that third-party [tax engine](/docs/20260301/product-modules/settings/glossary#tax-engine).

#### Prerequisites

* Connect the third-party tax engine to a business entity. For steps, see [Avalara AvaTax](/docs/20260301/third-party-integrations/tax-automation/avalara-avatax) or [Anrok](/docs/20260301/third-party-integrations/tax-automation/anrok). Until then, the panel shows **Connect tax tools** instead of a code field.

1. Go to **Settings** > **Tax Configuration**.
2. On the **Tax Categories** tab, open the menu of the tax category, and click **Edit**.
3. In **Avalara Tax Code**, enter the code. In **Anrok Tax Code**, select the code from the Anrok catalog.
4. Click **Save Changes**.

> [!NOTE]
>
> You can also map a code in the table. In the column of the third-party tax engine, click **Map Avalara code** or **Map Anrok code**, enter or select the code, and save. Zenskar confirms the mapping.

A new code for a third-party tax engine replaces the previous code for that engine.

### Remove a third-party tax code

> [!WARNING]
>
> A tax category without a code for a third-party tax engine can affect [contracts](/docs/20260301/product-modules/contracts/concepts/contracts) that bill customers in a served country for which the business entity uses that engine. Before you remove a code, change the tax engine of those served countries, or map a new code.

1. Go to **Settings** > **Tax Configuration**.
2. On the **Tax Categories** tab, open the menu of the tax category, and click **Edit**.
3. Clear the code field of the third-party tax engine.
4. Click **Save Changes**.

> [!NOTE]
>
> You can also click **×** next to the code in the table. Zenskar confirms that the code is removed.

## Manage served countries

### Add a served country

A [served country](/docs/20260301/product-modules/settings/glossary#served-country) is a country in which the business entity bills customers. The business entity uses one tax engine for each served country.

1. Go to **Settings** > **Tax Configuration**.
2. On the **Entities** tab, find the card of the business entity, and click **Configure**.
3. On the **Countries Serving** tab, click **Add Country**.
4. In **Select Country**, select the country.
5. In **Currencies**, select every currency in which the business entity bills customers in that country.
6. In **Tax Engine**, select **Zenskar**, or the third-party tax engine connected to this business entity.
7. Click **Add Country**.

Zenskar confirms the change. A served country covers only contracts in its currencies. A missing currency can affect [contracts](/docs/20260301/product-modules/contracts/concepts/contracts) in that currency.

### Add a currency, or turn a currency on or off

1. Go to **Settings** > **Tax Configuration**.
2. On the **Entities** tab, find the card of the business entity, and click **Configure**.
3. On the **Countries Serving** tab, open the menu of the country, and click **Edit**.
4. Do one or both of the following:
   * To add a currency, select it in **Add another currency**.
   * To turn a currency on or off, click it in the list of currencies. At least one currency must stay on.
5. Click **Save Changes**.

Zenskar confirms the change. A new currency uses the tax engine for the country. A currency that is off is hidden from the **Countries Serving** list.

### Change the tax engine for a served country

> [!WARNING]
>
> Zenskar does not check the mapping when you change the tax engine. If a tax category has no code for the new third-party tax engine, this can affect [contracts](/docs/20260301/product-modules/contracts/concepts/contracts) that bill customers in that country. Before you change to a third-party tax engine, [map your tax categories](#map-a-tax-category-to-a-third-party-tax-code) to codes in that engine.

1. Go to **Settings** > **Tax Configuration**.
2. On the **Entities** tab, find the card of the business entity, and click **Configure**.
3. On the **Countries Serving** tab, open the menu of the country, and click **Edit**.
4. In **Tax Engine**, select the new tax engine.
5. Click **Save Changes**.

Zenskar confirms the change. The change applies to every currency of the country that is on. The tax rates of the country stay configured. They apply again if you switch back to **Zenskar**.

### Move a business entity to a different third-party tax engine

A business entity can have at most one third-party tax engine connected. Zenskar does not translate codes from one third-party tax engine to another. Choose one of the following options.

**Option A: keep tax calculation running.** Use this option if the business entity has tax rates for the affected served countries.

1. Go to **Settings** > **Tax Configuration**.
2. On the **Entities** tab, find the card of the business entity, and click **Configure**.
3. For each served country for which the business entity uses the old third-party tax engine, change the tax engine to **Zenskar**. For steps, see [Change the tax engine for a served country](#change-the-tax-engine-for-a-served-country).
4. Disconnect the old third-party tax engine, and connect the new one. For steps, see [Avalara AvaTax](/docs/20260301/third-party-integrations/tax-automation/avalara-avatax) or [Anrok](/docs/20260301/third-party-integrations/tax-automation/anrok).
5. Map your tax categories to codes in the new third-party tax engine. For steps, see [Map a tax category to a third-party tax code](#map-a-tax-category-to-a-third-party-tax-code).
6. For each affected served country, change the tax engine to the new third-party tax engine.

**Option B: accept a gap.**

> [!WARNING]
>
> Between steps 1 and 3, the served countries for which the business entity uses the old third-party tax engine have no connected tax engine. This can affect [contracts](/docs/20260301/product-modules/contracts/concepts/contracts) that bill customers in those countries. To avoid the gap, use option A.

1. Disconnect the old third-party tax engine, and connect the new one.
2. Map your tax categories to codes in the new third-party tax engine.
3. For each served country for which the business entity used the old third-party tax engine, change the tax engine to the new one.

If the new third-party tax engine is already connected to another business entity in your organization, you can map the tax categories before you disconnect the old engine.

### Remove a served country

> [!WARNING]
>
> Zenskar removes the country immediately, without asking for confirmation. Removing a served country can affect [contracts](/docs/20260301/product-modules/contracts/concepts/contracts) that bill customers in that country. Before you remove a served country, make sure that no active contract bills customers in it.

1. Go to **Settings** > **Tax Configuration**.
2. On the **Entities** tab, find the card of the business entity, and click **Configure**.
3. On the **Countries Serving** tab, open the menu of the country, and click **Remove**.

Zenskar confirms the removal. Zenskar removes the country and all of its currencies. Zenskar keeps the tax rates of the country. If you add the country again, the tax rates apply again.

## Manage tax rates

### Add a tax rate

The Zenskar tax engine uses tax rates only for served countries where it is the tax engine.

> [!CAUTION]
>
> You cannot edit, end, or delete a saved rate change in the dashboard. Before you click **Add Tax Rate**, add every known future [rate change](/docs/20260301/product-modules/settings/glossary#rate-change). For steps, see [Schedule a rate change](#schedule-a-rate-change).

1. Go to **Settings** > **Tax Configuration**.
2. On the **Entities** tab, find the card of the business entity, and click **Configure**.
3. On the **Tax Rates** tab, click **Add Tax Rate**.

   **Add Tax Rate** is unavailable until the business entity has a served country. To add a tax rate for one tax category, you can also click **+ Tax Rate** next to that tax category.
4. In **Tax Category**, select the tax category.
5. In **Country**, select the served country.
6. Optional: narrow the [jurisdiction](/docs/20260301/product-modules/settings/glossary#jurisdiction). For steps, see [Narrow a tax rate to a state, city, or ZIP-code range](#narrow-a-tax-rate-to-a-state-city-or-zip-code-range).
7. In **Effective From**, select the start date.
8. In **Tax Name** and **Tax Percentage**, enter the first [tax component](/docs/20260301/product-modules/settings/glossary#tax-component).
9. Optional: to add more tax components, click **Add Another Component**.
10. Optional: to add later rate changes, see [Schedule a rate change](#schedule-a-rate-change).
11. Click **Add Tax Rate**.

Zenskar confirms the change. For how tax rates work, see [Tax rates](/docs/20260301/product-modules/settings/tax-configuration/concepts/tax-rates#tax-rates-what-the-zenskar-tax-engine-applies).

### Narrow a tax rate to a state, city, or ZIP-code range

In the **Add Tax Rate** panel, under **Where this rate applies**, do one of the following:

* For a state, click **Add State**. In **State**, enter the state.
* For a city, click **Add State**, and then click **Add City**. Enter the state and the city.
* For a ZIP-code range, click **Add ZIP Code**. Enter the state and the city. In **ZIP Code Start** and **ZIP Code End**, enter the range.

For a single ZIP code, enter the same value in **ZIP Code Start** and **ZIP Code End**. The start code and the end code must have the same length.

Enter the state, city, and ZIP code in the same format as the billing addresses of your customers. For the matching rule, see [How Zenskar matches a jurisdiction](/docs/20260301/product-modules/settings/tax-configuration/concepts/tax-rates#how-zenskar-matches-a-jurisdiction).

### Schedule a rate change

> [!CAUTION]
>
> After you save, you cannot add a later rate change for the same tax category and jurisdiction in the dashboard. Schedule every known rate change in the same **Add Tax Rate** panel as the first rate change.

1. In the **Add Tax Rate** panel, enter the first rate change. For steps, see [Add a tax rate](#add-a-tax-rate).
2. Click **Schedule Rate Change**.
3. In **Effective From**, select the date on which the change takes effect.
4. In **Tax Name** and **Tax Percentage**, enter the tax components of the change.
5. Optional: to add more rate changes, repeat steps 2 to 4.
6. Click **Add Tax Rate**.

Zenskar confirms that the rate changes are scheduled. Zenskar ends each rate change on the day before the next one starts. The last rate change has no end date.

If a rate change fails to save, Zenskar keeps the rate changes saved before it, and reports how many rate changes it saved. The remaining rate changes stay in the panel. Correct them, and then click **Add Tax Rate** again.

A new rate change can affect active [contracts](/docs/20260301/product-modules/contracts/concepts/contracts) that use the tax category.

### View the rate changes of a tax rate

1. Go to **Settings** > **Tax Configuration**.
2. On the **Entities** tab, find the card of the business entity, and click **Configure**.
3. On the **Tax Rates** tab, find the tax rate.
4. Click the number of rate changes in the row of the tax rate.

**Tax Rate Details** opens. It lists every rate change of the tax rate, with its status, start date, end date, and tax components.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.