Configuration
AvaTax is configured in two places:
- App settings — your Avalara credentials and the behaviour that applies everywhere.
- Channel settings — which channels use AvaTax, and the ship-from address each one calculates from.
Both are needed. Credentials alone don't switch anything on.
Connect to AvaTax
- In the portal, go to Settings → Apps → Avalara AvaTax.
- Fill in the Connection fields.
- Click Test connection.
- Click Save.
Connection settings
| Setting | Description |
|---|---|
| Account Number | Your Avalara account number, provided during account activation. |
| License Key | Your Avalara software license key. Stored as a secret — once saved it is never displayed back to you or to any app. |
| Environment | Sandbox connects to sandbox-rest.avatax.com; Production connects to rest.avatax.com. Defaults to Sandbox. |
| Company Code | The company profile within your Avalara account that transactions are reported under. |
Test connection
Test connection calls Avalara's ping endpoint with your saved credentials and reports back either the authenticated account or the exact error Avalara returned.
Use it whenever you change credentials, switch environment, or suspect a permissions problem. A failure here means every calculation would fail the same way, so it's the first thing to check.
Test connection uses saved settings
The test runs against what's currently stored, not what's typed into the form. Save first, then test.
Find your company code
Rather than copying the code out of the Admin Console, click Lookup companies. The app queries your Avalara account and lists the companies it contains; click Use on one to fill in the Company Code field.
The lookup needs working credentials, so do this after a successful Test connection. Selecting a company stages the value in the settings form — remember to Save.
Behaviour
| Setting | Effect when on |
|---|---|
| Disable AvaTax | Switches the integration off completely. No calls of any kind are made — no calculation, no committing, no voiding. Orders fall back to Hantera's native taxFactor tax behaviour. Existing tax already written to orders is left as-is. |
| Disable document recording | Tax is still calculated, but nothing is ever recorded in Avalara. No documents are committed and none are voided. Use this when another system — typically your ERP — is the system of record for filing. See Documents & Returns. |
| Enable client-side logging | Adds the full AvaTax request and response payloads to the order timeline entries. Leave this off in normal operation and switch it on when you or Avalara support are diagnosing a specific problem. |
Turning AvaTax off is safe
Disable AvaTax is independent of every other setting and takes effect immediately on the next order calculation. It's the switch to reach for if AvaTax is misbehaving and you need orders flowing again.
Tax codes and country scope
| Setting | Description |
|---|---|
| Enabled Countries | Comma-separated destination country codes that AvaTax calculates tax for. Defaults to US,CA. Deliveries to any other country are ignored by the app and keep their native tax. |
| Default Product Tax Code | The Avalara tax code applied to order lines that have no code of their own, e.g. P0000000 for general tangible personal property. |
| Default Shipping Tax Code | The Avalara tax code applied to shipping (freight) lines, e.g. FR020100. Shipping taxability varies by state, so this matters. |
Both defaults can be overridden per line — see Tax Codes.
Widening the country list
AvaTax supports far more jurisdictions than the US and Canada, and you can add their codes here. Be aware that only US and Canada are verified in this release; other destinations may need tax-code and address-format work specific to that country.
Configure each channel
Each Hantera channel decides for itself whether it uses AvaTax, and supplies the ship-from address that its tax is calculated from.
- Go to Settings → Channels and open the channel.
- Expand the AvaTax section and turn its toggle on.
- Fill in the Default Origin (ship-from) address.
- Optionally set a reporting location code or a company code override.
- Save the channel.
Repeat for every channel that should use AvaTax.
| Field | Description |
|---|---|
| AvaTax toggle | Explicit opt-in. With this off, the channel behaves as though the app weren't installed. |
| Default Origin (ship-from) | The address goods ship from for this channel. Required. At minimum a postal code and country — without them, no tax is calculated for the channel. |
| Reporting Location Code | Optional. An Avalara reporting location code, sent as the document's reportingLocationCode. Only relevant if you do location-based tax reporting in Avalara. |
| Company Code override | Optional. Reports this channel's transactions under a different Avalara company than the app-level Company Code. Useful when one Hantera instance serves several legal entities. |
Turning the toggle off preserves the other values, so you can switch a channel off and back on without re-entering its address.
An origin is not optional
US sales tax is determined by the jurisdiction pair — where goods ship from and to. Avalara rejects any transaction without both. The channel editor warns you while the origin is missing a postal code or country, and calculation is skipped for that channel until it's complete.
When tax is calculated
The app checks a series of conditions before contacting Avalara, and stops at the first one that fails. Understanding these explains both why a call happened and why one didn't.
| # | Condition |
|---|---|
| 1 | Disable AvaTax is off. |
| 2 | The order's channel has AvaTax enabled. |
| 3 | The order isn't cancelled. |
| 4 | At least one delivery has an address whose country is in Enabled Countries and which has a postal code. |
| 5 | The channel has a usable ship-from origin. |
| 6 | Something tax-relevant has changed since tax was last calculated. |
Only deliveries that pass condition 4 are sent to Avalara. On a mixed order — say one delivery to Texas and one to Germany — the Texas delivery is taxed by AvaTax and the German one keeps its native tax.
Why nothing recalculates on every save
Condition 6 is the important one for your Avalara call volume. The app keeps a digest of the tax-relevant inputs on the order and compares it before each calculation. Changing a customer's phone number or adding an internal note doesn't touch tax, so no call is made.
The inputs that do trigger a recalculation are:
- Order lines — added, removed, quantity or amount changed
- A line's or delivery's tax code
- Any delivery address field
- Shipping cost
- The customer code, entity/use code, or exemption certificate number
- Whether the order is tax-inclusive
- The channel's ship-from origin
With the Commerce app installed, this extends to carts: calculated tax is stored on the cart and replayed on every render, so rendering a cart costs no AvaTax calls at all. A typical checkout makes one call when the shipping address is entered, one more for each subsequent change, and one when the invoice is committed.
Configuring without the portal
Every app setting is also reachable through the app settings endpoints in the HTTP API, and channel configuration through the registry at channels/<channelKey> under the record's avatax field. This is the route for scripted or environment-promoted setups.
Settings keys, for reference: accountNumber, licenseKey, environment, companyCode, disabled, disableDocumentRecording, enableLogging, enabledCountries, defaultTaxCode, defaultShippingTaxCode.
Related
- Tax Codes — overriding the default codes per line
- Working with Orders — verifying a calculation and reading the timeline
- Documents & Returns — what gets recorded in Avalara