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

# Avalara (AvaTax)

# About

## **Provider-specific behaviors**

* Avalara uses a “commit” based call for reporting final tax amounts when the invoice is paid, unlike other providers that report tax at invoice issuance.

## **Geographic coverage**

Global — 190+ countries for VAT/GST; all US states for sales tax.

# Setup

## **Prerequisites**

1. **Organization address**: to accurately calculate tax with Avalara, Orb requires an account address set as the ShipFrom address in Avalara. Set this from the Orb dashboard under Settings > Invoices.
2. **Nexus in Avalara**: ensure your Avalara account is correctly configured with any nexus you're obligated to collect and remit tax in, including any newly added non-US/Canada nexus.

## **Connecting your account**

1. Navigate to **Settings > Taxes.**
2. Select “Connect to Avalara.”
3. Enter your Avalara username/password. We recommend provisioning a separate account for your Orb integration. Invalid credentials will error at this stage. For Orb test mode, use your Avalara sandbox credentials; for Orb live mode, use your Avalara production credentials.

## **Configuration options**

* Compute tax — when on, Orb always uses Avalara to compute tax on any invoice eligible for issuance. If a customer is tax exempt, Orb skips tax calculation for that customer.
* Commit tax — when on, Orb commits a transaction in Avalara when the invoice transitions from issued to paid. When off, Orb uses Avalara only for calculation, not reporting (see Avalara's docs on reportable transactions).
* Server side logging — when on, Orb logs requests and responses for every Avalara request. Logs can be made available on request via Slack.
* Avalara company code — the company Orb uses to create and report transactions.

## **Setting up tax codes**

Orb supports tax code configuration per Item, used during external syncs to ensure invoice line items map correctly to your tax/accounting services. Configure this under **Settings > Items > Item name > edit**. The external items dropdown is populated by Avalara's tax code list.

# **Sample request and response payload**

<Info>
  *The example below is illustrative of the shape Orb sends to and receives from Avalara AvaTax today, based on Orb's tax provider processors and test fixtures. Exact field names and structure can change as Avalara AvaTax versions its API — confirm against current behavior before relying on it for integration work.*
</Info>

### ***Request (Orb → Avalara AvaTax)***

```text theme={null}
{
  "companyCode": "def",
  "customerCode": "<orb_customer_id>",
  "lines": [
    {
      "amount": 450,
      "quantity": 1,
      "taxCode": "default-tax-code",
      "number": "abc",
      "description": "Price 1",
      "itemCode": "item_id",
      "taxIncluded": false
    }
  ],
  "taxOverride": {
    "type": "TaxDate",
    "reason": "Invoice date",
    "taxAmount": null,
    "taxDate": "2022-09-01"
  }
}
```

### ***Response (Avalara AvaTax → Orb)***

```text theme={null}
{
  "lines": [
    {
      "lineNumber": "abc",
      "isItemTaxable": true,
      "lineAmount": 450,
      "itemCode": "item_id",
      "quantity": 1,
      "reportingDate": "2022-09-01",
      "tax": 39.38,
      "taxableAmount": 450,
      "sourcing": "Destination",
      "taxCodeId": "default-tax-code",
      "details": [
        {
          "rateRuleId": "<rate_rule_id>",
          "tax": 39.38,
          "taxName": "State Tax",
          "rate": 0.0875
        }
      ]
    }
  ]
}
```

## **Committing the transaction (reporting)**

Avalara is Orb's one true “commit” flow -- the transaction is created during the calculation call above, and then when the Commit tax setting is enabled, Orb later commits that same document when the invoice transitions from issued to paid — this is the one provider where the reporting step is tied to payment rather than issuance.

### ***Commit call (Orb → Avalara)***

```text theme={null}
commit_transaction(
    company_code="<avalara_default_company_code>",
    transaction_code="<invoice_id>",
    model={"commit": True},
    include={"documentType": "SalesInvoice"}
)
```