Tax configuration

​

Concepts

Tax configuration consists of three settings. Together, they determine the tax on an invoice line.

​

Tax categories

Examples of tax categories are SaaS subscription and Professional services. You define tax categories once for your organization. Every business entity uses the same set. A tax category has the following properties:

• Code: an identifier that Zenskar assigns when you create the category, for example ZEN_TAX_00001. The code is a sequence number. You can’t change the code. Products and tax rates refer to a tax category by its code.
• Name: a display name. The name must be unique within your organization. You can rename a category without affecting the products and tax rates that use it.
• Provider tax codes: the Avalara tax code, the Anrok tax code, or both, that the category maps to. You can set a provider tax code only after you connect that provider.

You can’t delete a tax category.

​

Provider tax code mapping

A tax category can hold an Avalara tax code and an Anrok tax code at the same time. The tax engine that calculates tax for a line determines which code Zenskar uses: A provider tax code applies in every business entity that uses that provider. The mapping belongs to the category, not to the product. As a result, you don’t edit products when you connect a provider or change a country’s tax engine. You map the category to the new provider’s code instead. If a category has no code for the provider that calculates tax on a line, Zenskar can’t tax that line. With Anrok, Zenskar rejects the contract at activation. With Avalara, invoice generation fails. For details, see Contract activation checks.

​

Taxable line items

The tax category belongs to the product, not to the contract, the line item, or the price. A line item whose product has no tax category isn’t taxed. Zenskar doesn’t report this as an error. All prices are tax-exclusive. Tax-inclusive prices aren’t supported.

​

Countries, currencies, and tax engines

A served country is where your customers are, not where the business entity is located. Zenskar compares served countries with the country in each customer’s default billing address. For each served country, you configure the following:

• Currencies: the currencies in which the business entity bills customers in that country. A served country can have more than one currency.
• Tax engine: the engine that calculates tax for that country.

The tax engine belongs to a served country and currency pair. In the dashboard, all currencies of a served country use the same tax engine. Through the API, you can set a different tax engine for each currency.

​

Tax engine selection for a contract

Zenskar uses one tax engine for each contract. To select it, Zenskar uses the following values:

• The contract’s business entity.
• The country in the customer’s default billing address.
• The contract currency.

Zenskar finds the served country and currency that match these values. The tax engine of that served country and currency calculates tax for every taxable line item in the contract. If no served country and currency match, Zenskar doesn’t activate a contract that has taxable line items. For details, see Contract activation checks.

​

One third-party tax engine per business entity

A business entity can have only one third-party tax engine connected. The third-party tax engine is Avalara or Anrok. Zenskar rejects a connection to a second third-party tax engine. Every served country can still use the Zenskar tax engine. For example, one business entity can use the Zenskar tax engine for India and Avalara for the United States. The following diagram shows two business entities in one organization. Each entity connects a different provider. Each served country uses either the Zenskar tax engine or the entity’s provider. To move a business entity from one provider to the other, disconnect the current provider first. To use Avalara and Anrok at the same time, connect each provider to a different business entity.

​

Changing a country’s tax engine

When you change the tax engine for a served country, the following applies:

• Invoices that Zenskar generates after the change use the new tax engine.
• Approved invoices don’t change.
• Tax rates for the Zenskar tax engine stay configured. The rates apply again if you switch back to the Zenskar tax engine.

​

Removing a served country

When you remove a served country, Zenskar removes all of its currencies.

​

Disconnecting a provider

Disconnecting Avalara or Anrok doesn’t change the tax engine of any served country.

​

Zenskar tax rates

A tax rate belongs to one business entity. Each business entity maintains its own tax rates. You can configure tax rates for a served country regardless of its tax engine. The Zenskar tax engine uses the tax rates only when it’s the tax engine for that country. In the dashboard, you can add tax rates only for served countries.

​

Jurisdictions

You define a jurisdiction by setting one or more geographic levels. Each level narrows the level above it. A ZIP code range has the following rules:

• The start code and the end code must have the same length.
• The start code must be less than or equal to the end code.
• For a single ZIP code, use the same value for the start code and the end code.

Zenskar compares jurisdiction values with the customer’s billing address as text. Use the same form for both. For example, if customer addresses use CA for California, use CA in the tax rate.

​

Rate components

A tax rate has one or more rate components. A rate component has the following properties:

• Name: 1 to 50 characters. The name must be unique within the tax rate.
• Percentage: 0 to 100. The dashboard accepts up to two decimal places.

The Zenskar tax engine adds the rate components of a tax rate. For example, a tax rate with CGST at 9% and SGST at 9% applies 18% in total. Compound rates, where one component applies to an amount that includes another component, aren’t supported.

​

Effective periods

An effective period has a start date and an optional end date. Both dates are inclusive. A tax rate without an end date applies indefinitely. To change the percentage for a jurisdiction, you create a new tax rate with a later start date. The tax rates for one tax category and one jurisdiction form a sequence. Each tax rate in the sequence ends on the day before the next one starts. Zenskar rejects a tax rate that conflicts with the sequence:

• Two tax rates for the same tax category and jurisdiction can’t start on the same date.
• Their effective periods can’t overlap.
• Their effective periods can’t share a day. A tax rate that ends on June 30 and a tax rate that starts on June 30 conflict.

Tax rates for different jurisdictions can have overlapping effective periods. For example, a country-level tax rate and a state-level tax rate can apply at the same time. Each tax rate has one of the following statuses: You can deactivate a tax rate through the API. The Zenskar tax engine ignores a deactivated tax rate. A contract with taxable line items needs a tax rate for every day of its term. For details, see Contract activation checks.

​

Limits of the Zenskar tax engine

The Zenskar tax engine applies the rate components that you configure. It doesn’t apply tax rules such as reverse charge, place-of-supply rules, or nexus thresholds. It doesn’t update tax rates when tax authorities change them. You maintain every tax rate yourself. For a country that needs these rules, use Avalara or Anrok as the tax engine.

​

How Zenskar resolves tax for a contract

Before a tax engine calculates tax, Zenskar resolves the following for each contract:

• The tax destination.
• The tax origin.
• The tax engine.
• The tax inputs for each taxable line item.

​

Tax destination

Zenskar uses the customer’s default billing address as the tax destination. Zenskar doesn’t use the shipping address. The address must have a two-letter ISO country code. Zenskar uses the state, city, and ZIP code exactly as they appear in the address. All line items in a contract share one tax destination.

​

Tax origin

Zenskar uses the business entity’s address as the tax origin. Avalara and Anrok require a tax origin. The Zenskar tax engine doesn’t use it. The business entity’s address must include at least a country. If it doesn’t, invoice generation fails for contracts that use Avalara or Anrok.

​

Tax engine

Zenskar selects the tax engine from the business entity, the country of the tax destination, and the contract currency. For details, see Tax engine selection for a contract.

​

Tax inputs

Customer details include the customer’s custom attributes and tax IDs. They also identify the customer to the provider:

• Avalara: Zenskar identifies the customer by the Zenskar customer ID.
• Anrok: if the customer is mapped to an Anrok customer, Zenskar sends the Anrok customer ID. Zenskar doesn’t send the customer’s name or email in that case. Anrok applies the exemption certificates attached to its own customer record. If the customer isn’t mapped, Zenskar sends the Zenskar customer ID, name, and email.

​

When Zenskar resolves tax

Zenskar resolves tax each time it generates or previews invoices for a contract. Zenskar doesn’t store the result when you activate the contract. As a result, the following changes apply from the next invoice generation:

• Changes to tax rates.
• Changes to provider tax codes.
• Changes to the tax engine of a served country.
• Changes to the customer’s default billing address.

​

Contract activation checks

The checks prevent invoices that are missing tax. If a check fails, Zenskar doesn’t save the change. The error states what to fix. Zenskar runs the checks in the following cases:

• You activate a draft contract.
• You create a contract with the status active.
• You amend an active contract.

Zenskar doesn’t run the checks on draft contracts. Zenskar also skips the checks for a contract that has no taxable line items. Zenskar runs the following checks in order. Zenskar stops at the first check that fails. The tax engine check depends on the tax engine:

​

Tax rate coverage

For the Zenskar tax engine, tax rates must cover the whole contract term without gaps. Zenskar reports a gap at the start, in the middle, or at the end of the term. The error lists the dates that have no tax rate. The following rules define coverage:

• Two tax rates with consecutive effective periods are continuous. For example, a tax rate that ends on June 30 and a tax rate that starts on July 1 leave no gap.
• A contract without an end date needs a tax rate without an end date.
• Coverage is checked for each tax category in the contract separately.

​

What the checks don’t cover

The checks run only when a contract is activated or amended. Changes made after that aren’t checked. These changes include removing a served country, changing a tax engine, and changing a customer’s billing address. For their effects, see Removing a served country, Changing a country’s tax engine, and When Zenskar resolves tax.

​

How tax is calculated on an invoice

Zenskar calculates tax when it generates an invoice. Zenskar calculates tax separately for each taxable line item in each billing period.

​

Taxable amount

The taxable amount is the line item’s amount for the billing period after discounts and commitments. The tax engine calculates tax on the taxable amount. Zenskar adds the tax to the taxable amount.

​

Billing date and rate date

For prepaid billing, the billing date is the first day of the billing period. For postpaid billing, the billing date is the day after the billing period ends. One tax rate applies to the whole billing period. If a tax rate changes during a billing period, Zenskar doesn’t split the period. For example, take a monthly postpaid line item and a tax rate change on July 15. The July billing period uses the tax rate in effect on July 31. Avalara and Anrok receive the billing date.

​

Rounding

The Zenskar tax engine rounds tax as follows:

1. It calculates the tax for each rate component on the taxable amount.
2. It adds the component amounts to get the tax for the line.
3. It rounds the tax for the line to the smallest unit of the currency, for example 0.01 USD or 1 JPY. Rounding is half up.
4. It rounds each component amount the same way. If the rounded components don’t add up to the line’s tax, it adjusts the largest component by the difference.

The tax total of an invoice is the sum of the tax for each line. Zenskar doesn’t round again at the invoice level.

​

Tax exemption

Each tax engine handles tax exemption differently:

​

Tax estimates from Avalara and Anrok

When Zenskar generates an invoice, it requests a tax estimate from Avalara or Anrok. The provider doesn’t record an estimate as a transaction. Zenskar records the transaction with the provider when you approve the invoice. For details, see Approval-time recalculation. Zenskar doesn’t request estimates for billing dates more than three days in the future. Line items in those billing periods show no tax until Zenskar requests the estimate. Zenskar holds the approval of an invoice that contains such line items. Zenskar requests the estimate when it regenerates the invoice within three days of the billing date.

​

Failed tax calculation

Zenskar doesn’t generate an invoice with missing tax. Instead, invoice generation fails. Invoice generation fails in the following cases:

• Avalara or Anrok returns an error or can’t be reached.
• A tax category has no tax code for the provider that calculates its tax.
• The business entity’s address has no country, and the tax engine is Avalara or Anrok.
• The exempt_tax custom attribute isn’t a Boolean value.

​

Approval-time recalculation

Tax can change between invoice generation and approval. For example, a tax rate or a provider’s tax rules can change. Approval-time recalculation catches these changes before the invoice is final. Each tax engine recalculates tax in its own way:

​

Tax difference and the recalculation policy

If the tax on the invoice is zero and the recalculated tax isn’t, the tax difference is 100%. Zenskar compares the tax difference with a threshold. A tax difference at or below the threshold passes, and Zenskar approves the invoice. A tax difference above the threshold triggers the action set in your organization’s recalculation policy: By default, the threshold is 0% and the action is Hold. As a result, any tax difference holds the invoice. The dashboard has no setting for the policy. To change it, contact Zenskar support.

​

Other reasons Zenskar holds approval

Zenskar also holds approval in the following cases:

• The invoice has line items in future billing periods that Avalara or Anrok hasn’t priced yet. For details, see Tax estimates from Avalara and Anrok.
• A taxable line item has no tax record.
• Zenskar can’t complete the recalculation, for example because no tax rate applies or the provider returns an error.

When approval is held, the approval error states the reason. To resolve it, fix the cause and then regenerate the contract’s invoices. Then approve the invoice again.

​

After approval

After Zenskar approves the invoice, it records the tax with the provider:

​

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.

---

​

Walkthroughs

​

Create and map a tax category

This walkthrough creates a tax category, maps it to a connected Avalara account, and puts a product in that category, using a single SaaS subscription product as the example. It assumes Avalara is already connected under Integrations.

1. Go to Settings > Tax Configuration.
2. On the Tax Categories tab, click Add Tax Category.
   • Name: SaaS Subscription.
   • Avalara Tax Code: enter the code from Avalara’s tax code list (for example SW054000). This field is visible because Avalara is connected.
   • Click Save. Zenskar assigns it a code, for example ZEN_TAX_00002.
3. Go to Products, and open the product to tax, or start creating one.
4. In the Tax Category field, select SaaS Subscription. Save the product.

From here, any invoice line for this product, billed to a customer in a country where the business entity’s Tax Engine is Avalara, sends SW054000 to Avalara automatically. The product itself carries only the category; it has no Avalara-specific field of its own.

​

Switch a country’s tax engine

This walkthrough continues the example above: the business entity already serves a country with Tax Engine set to Avalara, and its products are tagged with categories mapped to Avalara Tax Codes. Anrok has since been connected, and the country is moving to Anrok.

1. Go to Settings > Tax Configuration > Tax Categories.
2. Open SaaS Subscription, and every other category used by products billed into that country. Fill in its Anrok Tax Code field, now visible because Anrok is connected, alongside the Avalara Tax Code already there. Click Save for each category. The category now carries both codes at once; saving one does not remove the other.
3. Switch to the Entities tab, click Configure on the business entity, and open Countries Serving.
4. Edit the country’s row and change Tax Engine from Avalara to Anrok. Save.

From here, new invoices for that country send the category’s Anrok Tax Code instead of its Avalara Tax Code. No product was edited: the switch was two category edits and one entity setting, because the category, not the product, carries the provider mapping. Invoices already generated under Avalara are unaffected, and other countries still routed to Avalara through the same categories continue to work, since a category can hold both provider codes at once.

​

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.

---

​

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

Example: A product is tagged with category ZEN_TAX_00007, and that category carries both an Avalara Tax Code and an Anrok Tax Code. The same product is sold to a customer whose billing country uses Avalara as its tax engine, and to another customer whose billing country uses Anrok. For the first invoice, Zenskar sends the category’s Avalara Tax Code; for the second, its Anrok Tax Code. The product itself was tagged once and never changes; only the country’s tax engine decides which of the category’s two mapped codes gets used. If a country’s engine later changes, or a new provider is connected, updating the category’s mapping is enough, no product needs to be re-tagged.

​

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.
  Changing a country’s tax engine takes effect immediately, and nothing checks in advance that every tax category used by that country’s customers already carries a code for the new engine. An unmapped category fails differently depending on the engine: with Anrok, the contract line fails to build its tax input; with Avalara, the invoice is instead held for review at approval. Map every affected category to the new engine’s code before switching, not after.
• 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.

---

​

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.