> For the complete documentation index, see [llms.txt](https://docs.commercelayer.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.commercelayer.io/core-api-reference/avalara_accounts.md).

# Avalara accounts

The Avalara account object and the allowed CRUD operations on the related resource endpoint

Configure your [Avalara](https://www.avalara.com/us/en/index.html) account to automatically compute tax calculations for the orders of the associated market. Set the `username`, `password`, and `company_code` attributes with your Avalara credentials.

You can also set the following optional attributes:

* `commit_invoice` — set it to `true` to have transactions recorded and visible on the Avalara website (more details [here](#connect-to-avatax)).
* `ddp` — set it to `true` if the seller is responsible for paying customs duty and import tax to customs authorities, a.k.a. Delivered Duty Paid (more details [here](#connect-to-avatax)).
* `pass_tax_exemption_code` — set it to `true` to let Avalara determine taxes for tax-exempt customers (more details [here](#pass-the-exemption-code-to-avalara)).

## Configuration guide

Avalara [AvaTax](https://www.avalara.com/us/en/products/calculations.html) is a cloud-based solution automating transaction tax calculations and the tax filing process. Avalara provides real-time tax calculation using tax content from more than 12,000 US taxing jurisdictions and over 200 countries, ensuring your transaction tax is calculated based on the most current tax rules.

AvaTax is integrated with Commerce Layer as a [tax calculator](/core-api-reference/tax_calculators.md) that connects to one or more markets. Once connected, every order placed in that market is taxed by Avalara in real time.

{% hint style="info" icon="image" %}
The screens below are taken directly from the Commerce Layer [Dashboard](https://dashboard.commercelayer.io/)'s *Settings* area.
{% endhint %}

{% stepper %}
{% step %}

### Connect to AvaTax

In Commerce Layer, AvaTax is added as a tax calculator from the organization's *Settings*:

* Go to *Settings › Tax calculators*.
* Click *+ New*, then select the *Avalara* tile from the list of integrated tax calculators.
* Enter your Avalara AvaTax credentials and click *Create*.

<figure><img src="https://4223484328-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FRWJeylueWkzLadK710XZ%2Fuploads%2FQBd6ufQ90gP8p78ZMPnb%2Fcreate-a-tax-calculator.jpg?alt=media&amp;token=d3599460-610f-4bd0-94a5-79b9edadbec7" alt=""><figcaption></figcaption></figure>

<table><thead><tr><th width="300">Field</th><th>Description</th></tr></thead><tbody><tr><td><strong>Account ID</strong></td><td>The Avalara account number provided during your AvaTax account activation.</td></tr><tr><td><strong>License Key</strong></td><td>The Avalara software license key provided during activation.</td></tr><tr><td><strong>Company code</strong></td><td>The company profile identifier configured in the AvaTax Admin Console.</td></tr><tr><td><strong>Record sales invoice on Avalara</strong></td><td>When enabled, transactions are posted and committed to the AvaTax Admin Console for record keeping (equivalent to <em>Enable Document Committing / Submission</em>).</td></tr><tr><td><strong>Delivered Duty Paid</strong></td><td>Enable when the merchant, rather than the customer, is responsible for import duties and taxes on cross-border shipments.</td></tr></tbody></table>

{% hint style="warning" icon="circle-exclamation" %}
Once created, the credentials cannot be viewed or edited from the Dashboard. To change them, delete the tax calculator and add a new one.
{% endhint %}
{% endstep %}

{% step %}

### Assign the tax calculator to a market

AvaTax only calculates tax for orders placed in a [market](/core-api-reference/markets.md) that has this tax calculator assigned. Go to *Settings › Markets*, open a market, click *Edit*, and select the *Avalara* tax calculator under *Automation*.

<figure><img src="https://4223484328-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FRWJeylueWkzLadK710XZ%2Fuploads%2FIQq0Rwu9ifpbf4jGelgd%2Fassign-to-market.jpg?alt=media&amp;token=289fa7cb-8236-4636-9c43-6559be4bba1a" alt=""><figcaption></figcaption></figure>

{% hint style="info" icon="arrows-repeat" %}
Repeat this step for every market that should use Avalara for tax calculation.
{% endhint %}
{% endstep %}

{% step %}

### Configure Avalara AvaTax

Once connected, open *Settings › Tax calculators* and select the account to review its configuration.

<figure><img src="https://4223484328-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FRWJeylueWkzLadK710XZ%2Fuploads%2FNFouCdNBEYWTsP4iMRs5%2Ftax-calculator.jpg?alt=media&amp;token=8b392bbd-be36-402f-8111-679a86481d56" alt=""><figcaption></figcaption></figure>

{% hint style="success" %}
This screen confirms the tax calculator type (Avalara), the Account ID, and which options are enabled — in this example, *Record sales invoice* is active.
{% endhint %}

{% hint style="info" icon="pen-nib-slash" %}
The *Credentials* section is read-only after creation, by design.
{% endhint %}
{% endstep %}

{% step %}

### Assign an AvaTax System Tax Code to a product

Commerce Layer maps individual [SKUs](/core-api-reference/skus.md) to Avalara tax codes through [tax categories](/core-api-reference/tax_categories.md), managed from the same tax calculator's *Tax categories* tab. This is the equivalent of assigning a product-level tax code in AvaTax.

<figure><img src="https://4223484328-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FRWJeylueWkzLadK710XZ%2Fuploads%2F2fWBrSXd7dDmOoYBndsb%2Ftax-categories.jpg?alt=media&amp;token=52672cd1-2649-4af7-b470-6aad47b5d6dc" alt=""><figcaption></figcaption></figure>

To create a new tax category from the Dashboard:

* Click *+ Category*.
* Enter the SKU code to categorize.
* Enter the corresponding AvaTax System Tax Code.
* Click *Create*.

<figure><img src="https://4223484328-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FRWJeylueWkzLadK710XZ%2Fuploads%2FHoMcLzLQhoAMtM54bojM%2Fnew-tax-category.jpg?alt=media&amp;token=28952816-0a8f-41b7-86a9-5a775a5f302b" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
Check [this page](https://taxcode.avatax.avalara.com) for the full listing of available AvaTax System Tax Codes. Any SKU without an assigned tax category uses the tax calculator's default tax treatment.
{% endhint %}

{% hint style="warning" %}
Tax category assignment lives on the tax calculator resource rather than on the product edit screen itself — there is no *Tax code* field on the SKU edit form in the dashboard.
{% endhint %}
{% endstep %}

{% step %}

### Check taxes on an order

Once a market is connected to the Avalara tax calculator, every order placed in that market shows a real, Avalara-calculated taxes line in its summary — no manual tax entry is required.

<figure><img src="https://4223484328-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FRWJeylueWkzLadK710XZ%2Fuploads%2FYfMBmpQrXeCY3YkBhUQe%2Forder-taxed.jpg?alt=media&amp;token=1723088f-47a6-46bc-9a9d-4a5efa288c62" alt=""><figcaption></figcaption></figure>

{% hint style="success" %}
In this example order, Avalara calculated $4.57 of tax on a $62.00 taxable amount (product subtotal plus shipping), based on the customer's delivery address and the product's tax category.
{% endhint %}
{% endstep %}
{% endstepper %}

## Tax exemptions and address validation

By default, when an order's [customer](/core-api-reference/customers.md) has a `tax_exemption_code`, tax calculation is skipped altogether: Avalara is not called and the order is not taxed. Any taxes previously calculated on the order are cleared at the next order refresh.

Address validation happens as part of the real-time AvaTax calculation call made at checkout for every order in a connected market.

### Pass the exemption code to Avalara

To let Avalara handle exemptions instead, set the `pass_tax_exemption_code` attribute of the Avalara account to `true`. It is a setting of the account, so you set it once when creating or updating the account, with no action required on orders or customers.

From then on, Avalara is called as usual for exempt customers too, and the customer's `tax_exemption_code` is sent as the transaction's [entity use code](https://knowledge.avalara.com/bundle/hps1656397152776_hps1656397152776/page/List_of_entity_use_codes.html) (e.g. `G` for resale). Avalara determines the taxes, including partial exemptions by jurisdiction or product, and the order taxes reflect its response. If `commit_invoice` is `true`, the exempt transaction is also recorded on Avalara.

{% hint style="warning" %}
Avalara does not validate the code: any code it does not recognize, or that does not apply to the order's country, is fully taxed with no error, so a wrong code never prevents an order from being placed. Codes are not case-sensitive. Make sure your customers' exemption codes match Avalara's standard entity use codes or the custom ones defined for your Avalara company. If you enable the option on an existing account, customers currently exempt with a code that is not an entity use code will start being taxed.
{% endhint %}

{% hint style="info" %}
Businesses that need to manage exemption certificates directly can do so in Avalara's own [Exemption Certificate Management](https://www.avalara.com/us/en/products/exemption-certificate-management-pro.html) product. Avalara matches certificates by customer code, which Commerce Layer sets to the customer's email, so register the certificates under that email.
{% endhint %}

### Validate the exemption code

To check a customer's code before taxes are calculated, update the [order](/core-api-reference/orders.md) with the `_validate_tax_exemption_code` trigger attribute set to `true`. The check runs only when you request it, so it never prevents an order from being placed.

If `pass_tax_exemption_code` is enabled, the code is checked against Avalara's standard entity use codes (including the countries each one applies to) and the custom ones found in your Avalara company's tax rules, when your credentials can read them. The request returns `422` if the code is not valid for the order's country, or if Avalara cannot be reached to verify it. Otherwise, as with any other tax calculator or with the option disabled, the order is updated as usual.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.commercelayer.io/core-api-reference/avalara_accounts.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.