> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dualentry.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Avalara AvaTax Integration: Setup and Sync

> Connect Avalara AvaTax to DualEntry to calculate U.S. sales tax in real time on invoices, sales orders, cash sales, and customer credits.

Connect [Avalara AvaTax](https://www.avalara.com/) to DualEntry so sales tax is calculated automatically when you create an invoice, sales order, cash sale, or customer credit. The integration pulls your AvaTax companies and nexuses into DualEntry, then calls AvaTax in real time during transaction entry to determine the correct tax rate and amount based on the customer's shipping address.

## Prerequisites

Confirm the following before connecting:

* An active Avalara AvaTax account, with your **Account ID** and **License Key** available.
* The companies you want to use exist in **both** DualEntry and AvaTax. DualEntry does not auto-create companies in AvaTax.
* Tax nexuses are configured in AvaTax for every jurisdiction where you collect tax.
* You know how each DualEntry company should map to an AvaTax company.

You also need a list of the AvaTax product tax codes you plan to use, so you can attach them to the corresponding DualEntry items during setup.

## Step 1: Connect the integration

Authorize DualEntry to call AvaTax with your account credentials.

1. Navigate to **Settings → Integrations → Avalara**.
2. Enter your Avalara **Account ID** and **License Key**.
3. Select the environment: **Sandbox** or **Production**.
4. Choose **Connect**. DualEntry validates the credentials against AvaTax and confirms the connection.

## Step 2: Run the initial sync

After connecting, DualEntry pulls reference data from AvaTax automatically:

* The list of AvaTax companies on your account.
* The tax nexuses configured for each company.
* Custom tax codes (optional, if your AvaTax account uses them).

The sync is on-demand from this point on. To refresh the data, choose **Sync** from the Avalara integration page.

## Step 3: Map companies

Each DualEntry company must be mapped to a corresponding AvaTax company before transactions can be taxed.

1. Open **Settings → Integrations → Avalara → Companies**.
2. For each DualEntry company, select the AvaTax company it corresponds to. The DualEntry `company_id` is sent to AvaTax as the company code on every transaction.
3. Save the mapping.

<Warning>
  Tax calculation fails for any DualEntry company that is not mapped to an AvaTax company. Verify mappings for every active entity before you go live.
</Warning>

## Step 4: Confirm nexus matching

DualEntry auto-matches nexuses by country plus region or state - for example, AvaTax `US-CA` matches DualEntry `US-CA`. Global nexuses where country equals region (e.g., `US-US`) are skipped.

1. Open **Settings → Integrations → Avalara → Nexuses**.
2. Review the matched nexuses for each company.
3. If a nexus is missing, create it in AvaTax and run **Sync** again.

## Step 5: Set up product tax codes

Map the AvaTax product tax codes you plan to use, then attach them to your DualEntry items so AvaTax can apply the correct exemptions or reduced rates.

1. Open **Settings → Tax Setup → Product Tax Codes** and add each AvaTax tax code you plan to use.
2. On each DualEntry `item`, set the **Product Tax Code** field to the appropriate code.
3. On each DualEntry `customer`, set the customer as **Taxable** or **Tax Exempt**.

Items without a tax code fall back to AvaTax's `DEFAULT` taxable code.

## Step 6: Validate and go live

Once mappings are in place, confirm the integration is ready for transaction flow.

1. Verify every active DualEntry company is mapped to an AvaTax company.
2. Verify every required nexus is matched.
3. Verify items that need specific tax treatment have a product tax code assigned.
4. The integration is now marked **Setup Complete**, and tax is calculated automatically on new transactions.

## What syncs

The integration moves reference data one way and calls AvaTax in real time for tax calculation:

| AvaTax data      | DualEntry record        | Direction                      | Frequency                             |
| ---------------- | ----------------------- | ------------------------------ | ------------------------------------- |
| Companies (list) | Company mapping         | AvaTax → DualEntry             | On-demand                             |
| Tax nexuses      | Nexus mapping           | AvaTax → DualEntry             | On-demand                             |
| Custom tax codes | Product tax codes       | AvaTax → DualEntry             | On-demand (optional)                  |
| Tax calculation  | Tax line on transaction | DualEntry → AvaTax → DualEntry | Real time during transaction creation |

Tax is calculated when you create any of these transaction types: `invoice`, `sales_order`, `cash_sale`, `customer_credit`. The customer's shipping address determines the jurisdiction.

## Mapping reference

The integration relies on the following field mappings between AvaTax and DualEntry.

**Company mapping**

| DualEntry | AvaTax               | Notes                                                                              |
| --------- | -------------------- | ---------------------------------------------------------------------------------- |
| Company   | Company Code         | Manual mapping required; DualEntry `company_id` is sent as the AvaTax company code |
| -         | Taxpayer ID Number   | Stored in AvaTax for reference and tax calculation                                 |
| -         | Tax Dependency Level | Used by AvaTax for multi-jurisdiction accuracy                                     |

**Nexus mapping**

| DualEntry field | AvaTax field | Matching rule                   |
| --------------- | ------------ | ------------------------------- |
| Country         | Country      | Must match exactly (e.g., `US`) |
| Region/State    | Region       | Must match exactly (e.g., `CA`) |

**Tax code mapping**

| DualEntry               | AvaTax    | Default behavior                            |
| ----------------------- | --------- | ------------------------------------------- |
| Item → Product Tax Code | Tax code  | Uses the assigned product tax code          |
| None assigned           | `DEFAULT` | Falls back to AvaTax's default taxable code |

## Current limitations

A few aspects of the integration are worth knowing before you rely on it:

* **Posted transactions only.** Draft transactions do not call AvaTax; tax is calculated on post.
* **Shipping address required.** Customers without a complete ship-to address cannot be taxed accurately. Verify ship-to and ship-from addresses on every taxable transaction.
* **One-way reference sync.** DualEntry does not push companies, customers, or items into AvaTax. Both systems must be configured independently.

## Troubleshoot tax calculation errors

When AvaTax returns an error or tax does not appear on a transaction, the most common causes are:

| Error                     | Cause                                                                       | Resolution                                                               |
| ------------------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| Company not mapped        | The DualEntry company has no AvaTax company mapping.                        | Add the mapping under Settings → Integrations → Avalara → Companies.     |
| No nexus for jurisdiction | AvaTax has no nexus configured for the customer's ship-to state or country. | Add the nexus in AvaTax, then choose **Sync** in DualEntry.              |
| Missing shipping address  | The customer record or transaction has no complete ship-to address.         | Add the customer's full ship-to address and recalculate the transaction. |
| Invalid credentials       | Account ID or License Key changed in Avalara.                               | Re-enter the credentials under Settings → Integrations → Avalara.        |

## Result

After completing these steps, sales tax is calculated automatically and accurately on every invoice, sales order, cash sale, and customer credit you post in DualEntry. To connect more systems, return to [Integrations](./index). To configure the customer and item records that feed tax calculation, see [Accounts Receivable](../core-financials/accounts-receivable/index).