Shipping and tax
The draft-and-publish model 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. You edit a draft, publish it when it’s right, and checkout only ever reads the published one.
Draft, published, archived
A config is in one of three states:
| State | Meaning |
|---|---|
draft | Being edited. Never used by checkout |
published | Live. Exactly one per application, per environment |
archived | A previous published version, kept for history |
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.
Editing does not go live. Saving a draft changes nothing a buyer sees — publishing does. This trips people up in the opposite direction too: publishing takes effect immediately for every checkout in that environment, with no staged rollout.
Because the published config is per environment, publishing 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.
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
Two limits worth knowing before you design around them:
- Tax exemption is per line-item category, not per customer. There is no customer-level tax-exempt flag, no VAT id or reverse-charge handling, and nothing passed to a tax provider for an exemption certificate.
- Exchange replacements are charged untaxed. The exchange path has no address-aware tax quote yet. See Refunds and returns.
Last updated August 9, 2026