Working with Orders

Once AvaTax is configured, tax appears on orders without anyone doing anything. This page covers the tooling for the cases that do need attention: exemptions, questionable addresses, and orders where something went wrong.

The AvaTax panel

Every order in an AvaTax-enabled channel gets an Avalara AvaTax panel in its sidebar.

Element	Meaning
Tax calculated by Avalara AvaTax	Avalara has successfully calculated tax for this order.
⚠ AvaTax error	The last AvaTax interaction failed. The order also carries an avatax-error tag so you can find these in order lists.
Total tax	The total tax Avalara returned for the order.
Calculated	When tax was last successfully calculated.
Last error	The code and message from the most recent failure, if there is one.

Per-line tax amounts aren't repeated here — they're in each order line's own breakdown.

Exemptions

There are two independent pieces of exemption data, and they do different jobs.

Entity/use code

An entity/use code says why a sale is exempt — the buyer is a reseller, a government body, a charity, and so on. It applies to the whole order.

Pick one from the Entity Use Code dropdown in the AvaTax panel. The list is fetched live from your own Avalara account, so it includes any custom codes you've defined. Each entry shows the code, its name and description, and the countries it's valid in — codes that aren't valid for this order's destination are greyed out but still selectable, since you may know better than the default validity list.

Selecting a code changes the tax, so the order recalculates on save.

Integrations can set this directly with setOrderDynamicFields on the avatax_entityUseCode field — useful for a B2B storefront that already knows the customer is exempt.

Exemption certificate number

The certificate number is the buyer's actual tax registration or exemption certificate identifier. This is not an AvaTax-specific field in Hantera: it comes from the order's invoice recipient tax ID, which you edit in the order's invoice recipient details like any other invoicing data.

The app sends it to Avalara as the document's exemptionNo. Because it affects tax, changing it triggers a recalculation.

Committed documents use the tax ID as it stood on the invoice when that invoice was raised, not the order's current value. Correcting a customer's tax ID afterwards doesn't retroactively alter documents already filed — which is the behaviour you want for an audit trail.

Validate an address

US tax is decided at street level, and an address that's nearly right can land in the wrong jurisdiction. Validate address in the AvaTax panel sends the order's delivery address to Avalara's address service and shows you the normalised version — corrected spelling, standardised abbreviations, and the full ZIP+4.

If Avalara can't resolve the address it tells you why. That's worth acting on before the order ships, because an unresolvable address usually means the tax is being calculated from a broader jurisdiction than the real one.

Force a recalculation

Recalculate tax clears the order's stored tax digest, which makes the app treat the next save as though everything had changed and call Avalara again.

You need this rarely — normal edits recalculate on their own. Use it when:

• You changed a default tax code and want an existing order to pick it up.
• You corrected the channel's ship-from address.
• A previous call failed and you want to retry immediately rather than wait for the next edit.

The order timeline

Every AvaTax call — successful or not — writes an entry to the order timeline. This is the audit trail and the first place to look when something's off.

Entry	When
Tax calculated by AvaTax: {total} {currency}	A calculation succeeded
AvaTax calculation failed: {code} {message}	A calculation failed, with Avalara's own error text
Invoice {number} committed to AvaTax ({type})	A document was recorded
AvaTax commit failed for invoice {number}: {code} {message}	Recording failed
AvaTax commit skipped for invoice {number}: {reason}	The document couldn't be built — usually a missing origin or delivery address
Invoice {number} voided in AvaTax	A document was voided

Switching on Enable client-side logging adds the full request and response payloads to these entries, which is what Avalara support will ask for. Switch it off again afterwards.

When a calculation fails

AvaTax failures never block an order. If Avalara is unreachable or rejects the request:

• The order keeps its previous tax, or falls back to Hantera's native tax behaviour if it had none.
• The order is tagged avatax-error and the panel shows an error badge.
• Avalara's exact error is written to the timeline and to the panel's Last error row.
• The stored digest is not updated, so the next edit retries automatically.

To find affected orders, filter your order list by the avatax-error tag.

Common causes

Symptom	Likely cause
No tax at all, no timeline entries	The channel isn't AvaTax-enabled, or the destination country isn't in Enabled Countries
Timeline says commit skipped: no origin	The channel has no ship-from address, or it's missing a postal code or country
Authentication errors	Wrong credentials, or credentials for the other environment. Run Test connection
Tax looks wrong for the product type	The line is falling back to the default tax code. See Tax Codes
Tax looks wrong for the location	Validate the delivery address

Fields reference

For integrators, the fields the app reads and writes on an order:

Field	On	Written by	Purpose
taxChecksum	Order	The app	Digest of the tax-relevant inputs. Treat as opaque.
avatax_calculatedAt	Order	The app	When tax was last successfully calculated
avatax_totalTax	Order	The app	Total tax from the last response
avatax_error	Order	The app	Last error { code, message }; cleared on success
avatax_entityUseCode	Order	Portal / integrations	Document-level entity/use code
avatax_entityUseCodeName	Order	Portal	Display cache for the panel label. Presentation only — never read when calculating.
avatax_taxCode	Order line	Portal / integrations	Per-line tax code override
avatax_taxCode	Delivery	Portal / integrations	Per-delivery shipping tax code override
avatax-error	Order tag	The app	Present while the last interaction failed

The exemption certificate number is the native invoiceRecipient.taxId, not a dynamic field.

Related

• Tax Codes — controlling how each line is taxed
• Documents & Returns — what happens when you invoice
• Configuration — the conditions for a calculation