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
Map of concepts
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.
Avalara connections: one Avalara company for one business entity
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:
- 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 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.
Setup of an Avalara connection
An Avalara connection starts without a Zenskar business entity. The setup of the connection has three parts, in the following order:- The first part sets the Zenskar business entity of the connection.
- 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.
- The third part maps the Zenskar tax categories to Avalara tax codes. These mappings apply in every Zenskar business entity. See Third-party tax codes.
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 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 asSW054000. 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:
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.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:
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.