Shipping and tax

The versioned configuration behind rates and tax rules, why exactly one config is live at a time, and how it differs from a connected provider.

Shipping rates and tax rules live in a single versioned configuration per application. Saving in the dashboard makes your edit live — checkout reads the published config, and Save writes it. The API keeps the two steps separate if you want them.

Draft, published, archived

A config is in one of three states:

Publishing archives the version it replaces, so you always have the config that was live when an old order was quoted. That matters when someone asks six months later why an order was taxed the way it was.

Save is live. In the dashboard, Save writes the draft and publishes it in one step, so what you saved is what buyers get — immediately, for every checkout in that environment, with no staged rollout. Over the API the two are separate calls: PUT /api/v1/shipping-tax/config/draft changes nothing a buyer sees until POST /api/v1/shipping-tax/config/publish.

Because the published config is per environment, saving in your test environment is a genuine rehearsal and has no effect on production.

What the config holds

Shipping — zones (where you ship), methods (the options a buyer picks), and rates. A handling fee is the one named surcharge primitive; anything else is a custom line item.

Tax — regions, rules, and components. Line items can carry a tax category so different goods are taxed differently.

Configured rates vs a connected provider

These are two different things and the distinction decides who is responsible when a number is wrong:

• Configured rates — your own table. Throttle computes from what you entered. You own correctness.
• A connected provider — a shipping carrier or a tax service like Avalara or TaxJar. Throttle asks them at quote time and passes back what they say.

A provider connection is per environment, like everything else, so a sandbox environment points at the provider’s sandbox.

Connecting a tax provider

Avalara is the connected tax provider we verify against a live account. Three things about the connection are worth knowing before you set it up:

The environment is not a choice you make in the dialog. It follows the workspace environment you are in — a non-production environment always reaches Avalara’s sandbox, production always reaches production. To connect production credentials, switch to the production environment first. This used to look like a free-text field, which was misleading: the value was never used.

The company code comes from your account. Enter your account id and license key, then look up the companies Avalara exposes and pick one. You can still type a code you know if the lookup fails — a provider outage should slow you down, not stop you. The lookup runs on the credentials you have typed and stores nothing.

Recording documents is a separate switch from calculating tax. Turn it off and Throttle still calculates — every quote is a read-only SalesOrder, which never appears in your filed returns — but it stops committing, refunding and voiding documents in Avalara. Leave it on if Avalara is where you file. Turn it off if you file from somewhere else and only want Throttle for the numbers. It is on by default, per application, and versioned with the rest of the published config.

Addresses can also be checked against Avalara before a buyer pays, in the US and Canada. A verdict that cannot be resolved is reported as unresolved, never as a failure — blocking a sale because address validation was unavailable would be worse than accepting an unvalidated address.

Setting it up end to end — credentials, company lookup, tax code mapping, customer exemptions, address validation and the call log — is covered step by step in the Avalara AvaTax setup guide.

Quoting from the browser

Shipping quotes and tax calculations are the only two things a publishable pk_ key can do. That is deliberate — they are stateless computes that take an address and a basket and return a number, reading nothing that already exists. Everything else needs a secret key on your server. See API keys and environments.

Known gaps

One limit worth knowing before you design around it:

• Exchange replacements are charged untaxed. The exchange path has no address-aware tax quote yet. See Refunds and returns.

Last updated August 30, 2026