# Avalara

## Overview

Avalara AvaTax is a cloud tax-compliance engine that calculates sales, use, and VAT tax in real time and validates addresses for accurate jurisdiction assignment. Connect Avalara to Fours so the Fours AI agent can compute tax on invoices and sales orders, commit or void tax transactions, validate customer addresses, and look up tax codes and companies on your Avalara account — keeping marketplace billing tax-compliant.

### Org-Level vs User-Level

> **Org-Level Only**: Avalara connects at the organization level using your Avalara Account ID and License Key. The connection is shared across your organization.

## Create Integration (Org-Level)

### Prerequisites

- An Avalara AvaTax account
- Your Avalara **Account ID** and a **License Key** (Avalara → **Settings → License and API Keys**)
- Your **Company Code** (used per transaction, not in the connection form)

### Authenticate by License Key

1. Navigate to Settings > Integrations
2. Click **Connect Avalara**
3. Fill in three fields:

   | Field | What it is |
   | ----- | ---------- |
   | **Account ID** | Your Avalara account identifier. |
   | **License Key** | The key from Avalara → **Settings → License and API Keys**. Stored as a secret. |
   | **Avalara Client** | Identifies Fours in AvaTax's request logs. **This value is ours, not yours** — it ships pre-filled with the correct default, so leave it alone unless Fours support asks you to change it. |

4. Save, then click **Verify** to confirm the connection

:::note
The integration connects to Avalara **production** (`https://rest.avatax.com`) by default. Advanced setups can target the Avalara **sandbox** (`https://sandbox-rest.avatax.com`) via the environment setting.
:::

## Fours AI Tools

When Avalara is connected, the Fours AI agent can run tax operations through Fours' built-in tools (13 actions). Capabilities are grouped below.

> **Org-level**: Tools run against the organization's connected Avalara account.

| Capability | What the agent can do |
|------------|-----------------------|
| **Tax calculation** | Estimate tax on a sales order or create a committed transaction from invoice data (e.g. `calculate-tax`, `create-transaction`) |
| **Transaction lifecycle** | Commit or void an existing transaction (e.g. `commit-transaction`, `void-transaction`) |
| **Address validation** | Validate and normalize an address (e.g. `resolve-address`) |
| **Reference & account data** | List companies and tax codes, and read the connected account (e.g. `list-companies`, `list-tax-codes`, `get-account`) |
| **Transaction lookup** | Read one transaction or list many (e.g. `get-transaction`, `list-transactions`) |
| **Adjustments** | Adjust an existing transaction (e.g. `adjust-transaction`) |
| **Jurisdiction reference** | List the company's locations and nexus registrations (e.g. `list-locations`, `list-nexus`) |

## Edit Integration

Editing is not supported. Delete and recreate.

## Delete Integration

Deleting removes the integration and revokes the stored Avalara credentials from Fours.

:::warning
This does not affect any transactions already recorded in Avalara. You may also want to revoke the License Key in Avalara (**Settings → License and API Keys**).
:::