Documents & Returns

Calculating tax and recording it are separate things in Avalara. Calculations are throwaway quotes; recorded documents are what Avalara files returns from. This page covers when Hantera records documents, and what they look like.

Calculations are never recorded

Every tax calculation the app makes — for a cart, a draft order, or a portal edit — is sent to Avalara as a SalesOrder document. Avalara treats these as quotes and never stores them, so they can be repeated freely without polluting your filing data.

Nothing is recorded until Hantera creates an invoice.

Invoices become recorded documents

When an invoice is created in Hantera, the app records it in Avalara.

Hantera invoice created  →  SalesInvoice committed to AvaTax
Credit invoice created   →  ReturnInvoice committed to AvaTax
Hantera invoice cancelled →  AvaTax document voided

Recording happens in the background, just after the invoice exists, and is retried automatically if Avalara is temporarily unavailable. The outcome is written to the order timeline either way.

What Avalara receives

Avalara field	From
code	The Hantera invoice number — unique and stable, so retries update the same document rather than duplicating it
referenceCode, purchaseOrderNo	The order number
date	The invoice's creation date
customerCode	The order's customer number, falling back to the invoice recipient's email
companyCode	The channel's company code override, or the app-level Company Code
commit	Always true — documents are recorded as final
Lines	One per invoice line, with its item code, description, quantity, net amount and tax code
Addresses	Ship-from from the channel origin; ship-to from the delivery each line belongs to

Because each line carries the address of its own delivery, an order shipped to several addresses is reported correctly against each jurisdiction from a single document.

Partial invoicing

Hantera invoices are deltas — invoicing part of an order now and the rest later produces two separate invoices. Each becomes its own AvaTax document with its own invoice number, so there's a one-to-one relationship between Hantera invoices and Avalara documents. No document is ever amended after the fact.

Returns and credit invoices

A return in Hantera produces a credit invoice. The app recognises it by its negative net and records it as a ReturnInvoice, following Avalara's rules for refunds:

Aspect	Value
Document type	ReturnInvoice
Amounts	Negative
Quantities	Positive
Document date	Today — the return is reported in the period it was processed
Tax date	The original invoice's date

That last row is what makes returns correct. The refund has to be credited at the rate the customer originally paid, not today's rate. The app finds the original invoice by following the credit line back to the line it reverses, and sends its date as a tax-date override so Avalara re-applies the historical rate.

Partial returns

Refunding part of a line works the same way. The credit invoice carries the returned portion, and Avalara credits tax proportionally at the original rate.

Voiding

Cancelling an invoice in Hantera voids the corresponding AvaTax document, marking it DocVoided in Avalara so it drops out of your filing.

This also covers rewinding an order. Rewinding to a checkpoint from before an invoice existed cancels that invoice, which voids the AvaTax document through exactly the same path.

Cancelling an order that was never invoiced needs no Avalara action, since nothing was ever recorded for it.

ERP as system of record

Many businesses already commit transactions to Avalara from their ERP. Recording them again from Hantera would double-count everything.

Switch on Disable document recording in the app settings. With it on:

• Tax is still calculated on carts and orders exactly as before.
• No documents are committed, and none are voided.
• Your ERP remains the sole source of Avalara documents.

This is a supported, first-class configuration — not a degraded mode. Hantera gives you accurate tax at checkout while your ERP owns the filing record.

Verifying documents

Two places to check:

• The order timeline in Hantera records every commit and void, including failures with Avalara's own error text. See the order timeline.
• The AvaTax Admin Console shows the documents themselves. Search by the Hantera invoice number, which is the document code.

If a document is missing, the timeline will say why. The most common reason is a commit skipped entry — the app couldn't resolve an origin or destination address, so it declined to send a document Avalara would have rejected.

Sandbox and production are separate

Documents committed while Environment was Sandbox exist only in Avalara's sandbox. Switching to production does not migrate them. Do your end-to-end testing in sandbox, then switch over before real trading starts.

Related

• Working with Orders — the timeline and troubleshooting
• Configuration — the document recording switch
• Order actor — invoicing and cancellation in Hantera