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

# Avalara AvaTax

## Avalara AvaTax

This document explains how Zenskar integrates with Avalara AvaTax through Avalara companies, Avalara connections, Avalara tax codes, Avalara customers, and Avalara transactions.

> **Map of concepts**
>
> | Concept | Details |
> | - | - |
> | [Avalara company](#avalara-connections-one-avalara-company-for-one-business-entity) | An Avalara company holds the committed Avalara transactions. |
> | [Avalara connection](#avalara-connections-one-avalara-company-for-one-business-entity) | Zenskar records Avalara transactions in the Avalara company of an Avalara connection. |
> | [Avalara tax code](#avalara-tax-codes-how-avalara-taxes-what-you-sell) | Each Zenskar tax category maps to one Avalara tax code. |
> | [Avalara customer](#avalara-customers-who-avalara-taxes) | Each Avalara transaction names one Avalara customer. |
> | [Avalara transaction](#avalara-transactions-what-zenskar-records) | Each line item of an Avalara transaction carries an Avalara tax code. |
>
> An Avalara connection links a Zenskar business entity to an Avalara company. Each Zenskar tax category maps to an Avalara tax code. Zenskar names the Avalara customer with the Zenskar customer ID. When a Zenskar invoice is generated, Zenskar asks Avalara for a tax estimate. When the Zenskar invoice is approved, Zenskar creates and commits its Avalara transactions.

> **Related modules**
>
> Avalara AvaTax uses the following modules:
>
> | Module | Details |
> | - | - |
> | [Tax configuration](/docs/20260301/product-modules/settings/tax-configuration/concepts/tax-configuration.md#tax-categories-how-products-are-taxed) | Each Zenskar tax category maps to one Avalara tax code. |
> | [Business entity](/docs/20260301/product-modules/settings/business-entity.md#organization-versus-business-entity) | Each Avalara connection belongs to one Zenskar business entity. |
> | [Custom attributes](/docs/20260301/product-modules/settings/custom-attributes.md) | Three custom attributes of a Zenskar customer mark it as exempt in Avalara. |
>
> The following modules use Avalara AvaTax:
>
> | Module | Details |
> | - | - |
> | [Tax configuration](/docs/20260301/product-modules/settings/tax-configuration/concepts/tax-configuration.md#served-countries-and-tax-engines) | A served country can use Avalara as its tax engine. |
> | [Contracts](/docs/20260301/product-modules/contracts/concepts/contracts.md#invoices-what-a-contract-produces) | The Zenskar invoices of a contract get their tax from Avalara. |

## Avalara connections: one Avalara company for one business entity

> [!NOTE]
>
> This page names each object by its system. A term that starts with "Zenskar", such as "Zenskar customer", names the object in Zenskar. A term that starts with "Avalara", such as "Avalara customer", names its equivalent in Avalara:
>
> | Zenskar | Avalara |
> | - | - |
> | Zenskar [business entity](/docs/20260301/product-modules/settings/glossary.md#business-entity) | [Avalara company](#avalara-connections-one-avalara-company-for-one-business-entity) |
> | Zenskar [tax category](/docs/20260301/product-modules/settings/glossary.md#tax-category) | [Avalara tax code](#avalara-tax-codes-how-avalara-taxes-what-you-sell) |
> | Zenskar [product](/docs/20260301/product-modules/products/glossary.md#product) | Zenskar does not create an Avalara equivalent. Each line item carries the Avalara tax code of the Zenskar product. |
> | Zenskar customer | [Avalara customer](#avalara-customers-who-avalara-taxes) |
> | Zenskar invoice | [Avalara transaction](#avalara-transactions-what-zenskar-records) |

An **Avalara company** is the Avalara equivalent of a Zenskar business entity.

In Avalara, an account holds one or more companies. Each company has a company code.

An **Avalara connection** is a link between one Zenskar business entity and one Avalara company.

An Avalara connection identifies the Avalara account by its account ID and license key. It identifies the Avalara company by its company code. Zenskar checks the account ID and the license key with Avalara. It does not check the company code.

> [!NOTE]
>
> * A Zenskar business entity can have only one Avalara connection. Different Zenskar business entities can use different Avalara companies, in the same Avalara account or in different ones.
> * A Zenskar business entity can have only one third-party [tax engine](/docs/20260301/product-modules/settings/glossary.md#tax-engine) connected. Zenskar rejects a second third-party tax engine.
> * The type of the Zenskar organization decides the Avalara environment. The credentials must belong to that environment:
>   * A sandbox Zenskar organization connects to Avalara sandbox.
>   * A production Zenskar organization connects to Avalara production.

Connecting Avalara does not switch any [served country](/docs/20260301/product-modules/settings/glossary.md#served-country) to Avalara. Each served country keeps its current tax engine until it is set to Avalara. See [Setup of an Avalara connection](#setup-of-an-avalara-connection).

## Setup of an Avalara connection

An [Avalara connection](#avalara-connections-one-avalara-company-for-one-business-entity) starts without a Zenskar business entity. The setup of the connection has three parts, in the following order:

1. The first part sets the Zenskar business entity of the connection.
2. The second part sets the served countries of the Zenskar business entity. It also sets the tax engine of each served country. See [Served countries and tax engines](/docs/20260301/product-modules/settings/tax-configuration/concepts/tax-configuration.md#served-countries-and-tax-engines).
3. The third part maps the Zenskar tax categories to [Avalara tax codes](#avalara-tax-codes-how-avalara-taxes-what-you-sell). These mappings apply in every Zenskar business entity. See [Third-party tax codes](/docs/20260301/product-modules/settings/tax-configuration/concepts/tax-configuration.md#third-party-tax-codes).

Parts 2 and 3 are available only after part 1 is complete.

## Avalara tax codes: how Avalara taxes what you sell

An **Avalara tax code** is the identifier of the Avalara equivalent of a Zenskar tax category.

Avalara uses the Avalara tax code of a line item to decide how to tax it. Avalara tax codes are the [third-party tax codes](/docs/20260301/product-modules/settings/glossary.md#third-party-tax-code) of Avalara. Each Zenskar tax category maps to one Avalara tax code. The mapping applies in every Zenskar business entity.

An Avalara tax code is text of up to 25 characters, such as `SW054000`. Zenskar does not check the code against the list of tax codes of Avalara.

## Avalara customers: who Avalara taxes

An **Avalara customer** is the Avalara equivalent of a Zenskar customer.

Zenskar names the Avalara customer with the Zenskar customer ID. When a Zenskar invoice has a payer, Zenskar uses the ID of the payer instead.

Zenskar sends the billing address of the Zenskar customer with each Avalara transaction. For most countries other than the United States, Zenskar also sends the tax ID of the Zenskar customer for that country. Avalara receives it as the business-identification number.

Three custom attributes of the Zenskar customer mark it as exempt in Avalara:

| Custom attribute | Effect in Avalara |
| - | - |
| `exempt_tax` | When the value is true, Avalara treats the transactions of the Zenskar customer as exempt. |
| `tax_exemption_number` | Zenskar sends the value as the exemption-certificate number. When the value is empty, Zenskar sends `exempt`. |
| `entity_use_code` | Zenskar sends the value as the Avalara entity-use code. The code states the reason for the exemption. |

Zenskar sends `tax_exemption_number` and `entity_use_code` only when `exempt_tax` is true.

## Address validation

When a Zenskar customer is created or updated, Zenskar asks Avalara to validate the billing address of the Zenskar customer. This happens only when the Zenskar customer's business entity has Avalara connected. Zenskar stores the result with the address.

Zenskar does not act on the result. The dashboard does not show it. An invalid billing address does not block contract activation. The effect of the address comes later, when Avalara calculates tax for a Zenskar invoice. This can affect [invoices](/docs/20260301/product-modules/contracts/concepts/contracts.md#invoices-what-a-contract-produces).

## Avalara transactions: what Zenskar records

An **Avalara transaction** is a record in Avalara of the tax of a Zenskar invoice.

Zenskar works with Avalara at two points of a Zenskar invoice:

| When | What happens |
| - | - |
| A Zenskar invoice is generated | Zenskar asks Avalara for a tax estimate. Avalara does not record the estimate. |
| A Zenskar invoice is approved | Zenskar creates the Avalara transactions of the Zenskar invoice. It compares their tax with the tax on the Zenskar invoice. Then it commits the Avalara transactions. |

Avalara includes only committed Avalara transactions in tax returns. A Zenskar invoice can have more than one Avalara transaction. Zenskar sends the invoice email at approval. The email does not wait for the commit.

Zenskar names each Avalara transaction. The ID has the form `{Zenskar invoice ID}:`, followed by eight characters. Avalara shows it as the document code. For example, a Zenskar invoice with the ID `e6654fc6-…` can have the Avalara transaction `e6654fc6-…:1a2b3c4d`.

Disconnecting Avalara removes the links between Zenskar invoices and their Avalara transactions. The Avalara transactions stay in Avalara.

The estimate, the comparison, and the commit can affect [invoices](/docs/20260301/product-modules/contracts/concepts/contracts.md#invoices-what-a-contract-produces).

## Work that stays in Avalara

Zenskar uses Avalara to calculate tax and to record Avalara transactions. The following work stays in Avalara:

| Work | Details |
| - | - |
| Filing and remittance | Tax returns and tax payments happen in Avalara, from the committed Avalara transactions. |
| Nexus | Nexus is set up in each Avalara company. Avalara returns no tax for a jurisdiction where the Avalara company has no nexus. |
| Avalara companies | Avalara companies and their company codes are created in Avalara. |
| Exemption certificates | Exemption certificates are managed in Avalara. Zenskar sends only the exemption-certificate number and the entity-use code. |


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