Tax Codes

Avalara tax codes tell AvaTax what kind of thing is being sold, which determines how each jurisdiction taxes it. Clothing, groceries, digital goods, software licences and shipping are all taxed differently — often differently within the same state.

Getting these right is what makes AvaTax accurate. Everything else is plumbing.

Where codes live in Hantera

In Hantera, tax codes are assigned to the order line and the shipping line, not to a central product record inside this app. Every line sent to Avalara carries a code resolved at calculation time.

Order lines

Priority	Source
1	The order line's own tax code, if one is set
2	The Default Product Tax Code app setting
3	Nothing sent — Avalara then treats the line as P0000000, general tangible personal property

Shipping lines

Each delivery with a shipping cost is sent to Avalara as its own freight line.

Priority	Source
1	The delivery's own tax code, if one is set
2	The Default Shipping Tax Code app setting
3	Nothing sent

Set the defaults first

Most catalogues are dominated by one kind of item. Set Default Product Tax Code to whatever covers the bulk of what you sell and only override the exceptions. Same for shipping: FR020100 covers ordinary shipping charges in most states.

Assign a tax code to an order line

1. Open the order in the portal.
2. Expand the order line you want to change.
3. Next to Tax Code, click Edit.
4. Search for the code in the Tax Code Lookup dialog and select it.
5. Save the order.

The lookup searches Avalara's live tax code catalogue through your own account, so it includes any custom codes your account defines. You can also browse the full list at taxcode.avatax.avalara.com.

The Tax Code row shows Default when the line has no code of its own, meaning the app-level default applies. Once a code is set, Reset removes it and returns the line to the default.

Changing a tax code changes the tax, so saving triggers a recalculation of the order.

Only visible on AvaTax channels

The Tax Code row only appears on orders in a channel that has AvaTax enabled. Orders in other channels don't show it, because the code wouldn't be used.

Assign a tax code to a shipping line

Shipping works identically. Expand the delivery's shipping line, click Edit next to Tax Code, and pick a code. This overrides Default Shipping Tax Code for that delivery only.

This is worth using when a single order mixes shipment types that are taxed differently — for example a standard parcel alongside a delivery-and-installation service.

Setting codes from an integration

Tax codes are ordinary dynamic fields, so any integration, import, or rule can set them:

Target	Command	Field
Order line	setOrderLineDynamicFields	avatax_taxCode
Delivery (shipping)	setDeliveryDynamicFields	avatax_taxCode

Setting the field to null clears the override.

This is the intended integration point. The AvaTax app deliberately reads the code from the line and nowhere else, which keeps it independent of how — or whether — you model a product catalogue.

Where tax codes usually come from

On a real project you don't set tax codes order by order. The product's tax code is catalogue data, maintained once per product in a PIM or in a product-management app such as Products, and copied onto each order line as the order is enriched.

A small rule on the OnOrderCommands hook does the copying:

param input: OnOrderCommands

// Product tax codes are catalogue data. Copy each line's product-level code onto
// the line so AvaTax picks it up, leaving lines with an explicit override alone.
from
  input.order.deliveries
  select d =>
    d.orderLines
    where ol => ol.dynamic->'avatax_taxCode' is not text
    select ol => {
      effect = 'orderCommand'
      type = 'setOrderLineDynamicFields'
      orderLineId = ol.orderLineId
      fields = {
        avatax_taxCode = lookupProductTaxCode(ol.productNumber)
      }
    }
  flatten
  buffer

The rule that owns this lives in the app that owns the catalogue, not in the AvaTax app — the coupling to product data belongs where the product data is. The portal editors then act as a per-order override on top of whatever the catalogue supplied.

Checking what Avalara actually used

The tax code sent for each line is part of the AvaTax request. To see it, switch on Enable client-side logging in the app settings and open the order's timeline — the calculation entry then includes the full request payload, with each line's taxCode.

Switch it back off once you're done; it's a diagnostic aid, not something to leave running.

Related

• Configuration — setting the default codes
• Working with Orders — the order panel and the timeline
• Avalara tax code reference — the full searchable catalogue