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, shipping, and derivative fees 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 classifications belong to the taxable base: an order line, a fee, or a delivery's native shipping line. Every line sent to Avalara carries a code resolved at calculation time.

Order lines

Priority	Source
1	The order line's avatax classification for the delivery country, then its default classification
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 shippingTaxClassifications.avatax entry for the delivery country, then its default entry
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.

Fees

Fees are derivative charges attached to either a delivery or an order line. They are not shipping lines.

Priority	Source
1	The fee's avatax classification for the delivery country, then its default classification
2	The Default fee tax code for that fee type
3	The Default Product Tax Code
4	Nothing sent

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 writes the delivery's native shipping classification for its destination country and 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

Integrations write the native replace-all classification maps. The map shape is always:

{ system -> { jurisdiction -> code } }

For example, a shipping integration can set the code for United States freight:

from {
  effect = 'orderCommand'
  type = 'setShippingTaxClassifications'
  deliveryId = deliveryId
  taxClassifications = {
    'avatax' -> { 'US' -> 'FR020100' }
  }
}

setShippingTaxClassifications replaces the full map. Preserve classifications for other systems and jurisdictions when updating one entry. The corresponding order-line and fee commands are setOrderLineTaxClassifications and setFeeTaxClassifications.

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 as a native classification so AvaTax picks it up.
from
  input.order.deliveries
  select d =>
    d.orderLines
    select ol => {
      effect = 'orderCommand'
      type = 'setOrderLineTaxClassifications'
      orderLineId = ol.orderLineId
      taxClassifications = {
        'avatax' -> { 'default' -> 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, click View AvaTax calls on the order's AvaTax panel and select the calculation — its request payload lists each line with the taxCode that was actually sent. See Diagnosing AvaTax calls for how to enable payload capture first.

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