Tax configuration

​

1. Concepts: How tax configuration works in Zenskar

Settings > Tax Configuration is where you tell Zenskar what gets taxed, where each of your business entities does business, and how tax should be calculated in each of those places. It has two levels:

• An organization level (the main Tax Configuration page) where you maintain a shared catalog of tax categories.
• A business entity level (reached by clicking Configure on an entity) where you set up the countries that entity serves and, for any country where Zenskar calculates tax itself, the actual tax rates.

​

Tax categories

A tax category is a reusable label for “what kind of thing is being taxed,” for example GST - Software Services, Sales Tax, or VAT - Digital Goods. Categories are shared across your entire organization: you define them once, then reference the same category from tax rates in any business entity, and from products. Every category gets a system-generated code (ZEN_TAX_00001, ZEN_TAX_00002, and so on) that never changes. You control the display name. If you have connected Avalara or Anrok as a tax integration, each category can also carry that provider’s code (an Avalara Tax Code or an Anrok Item Code), so the mapping between how Zenskar classifies this and how the provider classifies this lives in one place. Without a connected provider, this mapping is hidden, since there is nothing to map to yet.

​

Countries serving, currencies, and tax engines

For each business entity, Countries Serving is the list of countries you bill customers in. For every country you add, you choose:

• Which currencies you bill in for that country (a country can have more than one).
• Which tax engine calculates tax there: Zenskar, Avalara, or Anrok.

The tax engine choice matters per country, not globally: one entity could use Zenskar’s own rates for India while delegating tax in the UK to Avalara.

• Zenskar as the engine means you configure your own jurisdiction-based tax rates (below), and Zenskar computes tax from them at invoice time.
• Avalara or Anrok means Zenskar calls out to that connected provider at invoice time, and the provider returns the tax to apply. You do not maintain rates in Zenskar for that country.

​

Zenskar tax rates and jurisdictions

When a country’s tax engine is Zenskar, you configure the actual rates yourself, per tax category, at a level of geographic detail you choose:

• Country (required)
• State (optional)
• City (optional, requires a state)
• ZIP/postal code range (optional, requires a state and city)

Each jurisdiction/category combination holds one or more rate components: a name (for example CGST) and a percentage (for example 9%). A single jurisdiction commonly needs more than one component (for instance CGST: 9% plus SGST: 9% for an Indian state); Zenskar adds them together (rate stacking is additive today). Matching a customer to a rate. At invoice time, Zenskar looks for the most specific rate that matches the customer’s billing destination, checking ZIP, then city, then state, then country, and stopping at the first level with a configured rate. In practice this means:

• A country-level rate acts as the default for every customer in that country.
• Adding a more specific state, city, or ZIP-level rate for the same category overrides the country-level default for just that location. The country-level rate still covers everyone else.

Effective dating. Each rate carries an effective-from date, and you can schedule a future rate change for the same jurisdiction and category ahead of time. Zenskar shows it as Scheduled until it takes effect, then Active, then Expired once superseded. Two schedules for the same jurisdiction and category cannot share an effective date, and their date ranges cannot overlap or touch. Each new schedule effectively closes out the one before it. No silent zero-tax. If a country’s tax engine is Zenskar and no rate covers a customer’s destination (or a jurisdiction exists but has no active rate components), Zenskar does not charge 0% by default. It blocks invoice or contract activation until you add the missing coverage. This fail-closed behavior does not apply when the engine is Avalara or Anrok, since those providers resolve the rate themselves.

​

How this relates to other tax-adjacent settings

• Business Entity > Tax Information (VAT ID / PAN / GSTIN / Tax ID) is a separate, simpler feature: it records your own entity’s tax registration numbers for compliance recordkeeping. It does not drive tax calculation. That is what Tax Configuration is for. See Business entity.
• Products can be tagged with a tax category. Zenskar shows the assigned category on the product as a link back to this page (along with its mapped Avalara code, if one is set). The actual rate applied on an invoice is resolved from the customer’s destination, business entity, and effective date, not fixed on the product itself.

---

​

2. Walkthrough: Set up Zenskar-calculated tax for a country

This walkthrough sets up native (non-connector) tax for a business entity serving India, using a two-component GST rate (CGST + SGST) as the example, then schedules a future rate change.

1. Go to Settings > Tax Configuration.
2. On the Tax Categories tab, click Add Tax Category.
   • Name: GST - Software Services.
   • Leave the Avalara/Anrok code fields alone unless you have connected one of those providers and want to map this category to a provider tax code.
   • Click Save. Zenskar assigns it a code like ZEN_TAX_00001.
3. Switch to the Entities tab and click Configure on the business entity you want to set up.
4. On the entity’s Countries Serving tab, click to add a country:
   • Country: India.
   • Currencies: select INR.
   • Tax Engine: Zenskar.
   • Save. India now appears in the Countries Serving table with the Zenskar badge.
5. Switch to the entity’s Tax Rates tab and click Add Tax Rate.
   • Tax Category: GST - Software Services.
   • Where this rate applies: Country = India. Leave State/City/ZIP unset for a country-wide rate.
   • Under Tax Rate, set the Effective From date and add two components: CGST at 9% and SGST at 9%.
   • Click Save. The rate shows as Active (or Scheduled, if the effective date is in the future).
6. To see scheduling in action, open the same rate again and click Schedule Rate Change. Give the new schedule a later Effective From date and a different rate (for example CGST: 9.5%, SGST: 9.5%). Save.
   • The rates table now shows an rate changes link on that jurisdiction row. Clicking it opens a read-only history showing the current schedule as Active and the new one as Scheduled, with the boundary between them handled automatically.

From here, any invoice generated for a customer under this business entity, billed in INR, with a destination in India, picks up the active GST rate for that date automatically.

---

​

3. How-to guides

​

Manage tax categories

• Create a category: Settings > Tax Configuration > Tax Categories > Add Tax Category. Enter a Name (required); the Code is generated automatically and cannot be changed.
• Map a category to Avalara or Anrok: open the category and fill in the Avalara Tax Code and/or Anrok Item Code fields. These only appear once the corresponding connector is configured under Integrations. If neither is connected, use the Connect tax tools link shown in the panel instead.
• Rename a category or edit its provider mapping: click the category’s row to reopen the same panel. The category’s Code is permanent; only the name and provider mapping can change.

​

Manage countries a business entity serves

• Add a country: on the entity’s Countries Serving tab, add a country, choose one or more currencies, and pick a tax engine (Zenskar/Avalara/Anrok).
• Add or remove a currency for an existing country: edit the country row. Toggling a currency off keeps its history but blocks new invoices in that currency; at least one currency must stay enabled.
• Change the tax engine for a country: edit the country row and change Tax Engine. This affects future invoices only.
• Remove a country entirely: use the row menu’s Remove option. This removes all currencies configured for that country in one action.

​

Manage Zenskar tax rates

• Add a rate for a country: on the entity’s Tax Rates tab, click Add Tax Rate, pick the Tax Category, set Country, and add one or more components effective from a date.
  You can only pick from countries already added under Countries Serving for that entity. Add the country first if it is not in the dropdown.
• Add a state/city/ZIP-level override: in the same panel, use + Add State, then + Add City, then + Add ZIP Code to narrow the jurisdiction. Each level requires the one above it to be filled in first (a ZIP needs a city and state; a city needs a state). For a single ZIP code rather than a range, enter the same value for the start and end.
• Schedule a future rate change: open an existing rate (or add a new one) and click Schedule Rate Change to add another effective-dated set of components. Status pills show Active, Scheduled, and Expired schedules on the same jurisdiction.
• Review a jurisdiction’s full rate history: click the rate changes link on a jurisdiction row in the rates table to open a read-only view of every schedule, its date range, and its components.

​

Troubleshooting

• “Overlapping rate window” or similar conflict when saving a schedule: two schedules on the same jurisdiction and category cannot share a start date, and one schedule’s range cannot overlap, or touch on the same day, another active one. Adjust the new Effective From date so it starts the day after the previous schedule ends, or after its start date if it is open-ended.
• “Saved of rate changes”: if you added several schedules to one rate at once and one of them failed validation, the ones that succeeded are kept. Only the failed schedule(s) remain in the form for you to fix and resubmit.
• Cannot select a country in Add Tax Rate: the country needs to be added under Countries Serving on that entity first.
• Invoice or contract activation blocked citing missing tax coverage: the customer’s destination (or the effective date) is not covered by any active Zenskar rate for the relevant category. Add a rate for that country (or the more specific state/city/ZIP) that covers the date in question, or switch that country’s tax engine to a connected provider.

---

​

4. Reference

​

Location

Settings > Tax Configuration (organization level), then Configure on a business entity, then the entity-level page with Countries Serving and Tax Rates tabs.

​

Data model

Tax category Country / currency configuration (“Countries Serving” row) Tax rate jurisdiction Rate component

​

Rate status

​

Validation rules

​

API reference

Programmatic access to tax categories and jurisdiction rates. All endpoints require an API key with organization read access; write operations additionally require permission to update organization configuration.