When a US merchant asks us to “turn on sales tax”, they expect a configuration screen. There is one, and it is the easiest part of the job. What nobody shows on that screen is the data contract behind it: which states the business has nexus in, which orders recalculate tax, which totals carry shipping tax, and which payment links carry the correct amount. In the last year of production work, we fixed eight tax bugs in ten days on one project. Not one of them was a provider setup. All of them were data flows.
The provider can calculate the correct tax only when it has the correct state, address, items, shipping, and order state. Every commerce stack has several ways for that contract to break.
Here is what that failure surface actually looks like, and where it hides.
The settings fallacy
Most commerce backends expose a tax module: connect a provider, define a rate, and the checkout applies it. The module exists in Medusa, in Shopify, in any platform that sells to the US market. That part works.
The problem is that US sales tax is not one rate. It depends on at least four parts of the same data contract staying consistent:
- A nexus and registration state list: the states where the business has determined it must collect tax due to physical or economic nexus. Economic nexus thresholds vary by state and may depend on sales volume, the types of sales included in the calculation, and, in some states, transaction count.
- Per-state tax context, because sourcing, product taxability, local jurisdictions, exemptions, and shipping treatment differ across states. A single rate setting is fiction.
- Order lifecycle recalculation, because tax is computed at cart time, but orders change after that. Drafts become orders, items get added, addresses change, discounts apply.
- Line-level presentation, because item tax, shipping tax, and order adjustments are separate obligations that need separate lines.
The provider can calculate tax based on the context you provide. It cannot fix missing registrations, stale addresses, skipped order paths, or lifecycle events that never call it.
The draft order is the blind spot
Draft orders look like they aren’t real orders yet, so the tax logic is skipped. In practice, a draft order becomes a real order: the customer gets a payment link, pays the amount on it, and the amount was computed without tax, or with stale tax.
On the project that produced the eight fixes, the sequence was:
- Draft orders were not recalculating tax at all.
- When they did, US and non-US orders took different recalc paths, and the US path was the one breaking.
- The POS app created its own draft orders and did not calculate US sales tax on them.
- The payment link a customer received carried the wrong tax amount.
Each of these is a separate code path: the admin panel, the POS app, and the storefront payment link. Fixing the cart path does not fix any of the others.
A stale nexus list creates historical exposure
Crossing an economic nexus threshold does not generally make earlier sales retroactively taxable. The problem is discovering that the business already had a collection obligation, while the commerce system still treated the state as out of scope.
When that happens, fixing the nexus list fixes the next order. It doesn’t fix orders placed after the obligation began and before the system caught up.
That gap may only become visible during reconciliation or filing, months after the affected orders shipped. A business that thinks it is compliant because the tax provider is connected may discover the gap in the tax return, the most expensive place to find it.
Shipping tax needs to stay visible
Shipping charges are taxable in some situations and not in others, depending on the state and transaction. If the order summary collapses everything into one “tax total”, the merchant cannot see which states they are collecting shipping tax in, and reconciliation against the tax provider’s records breaks. The fix that separated US shipping tax in the order summary looks cosmetic from the outside. It is a compliance line item.
Tax recalculation must be idempotent
If a recalculation path adds new tax lines without replacing the previous calculation, touching the same order twice can double the tax. This is the kind of bug that surfaces as “the tax total is wrong” with no obvious cause, because the recalc path only misbehaves when the same order is touched more than once.
What this costs you if you get it wrong
The cost is not the tax itself. It is the surprise at filing time: undercollected tax in states you thought you had handled, a payment link that charged a customer the wrong amount, and a reconciliation that does not add up. For a US-facing merchant, fixing any of these costs more than the tax would have because it becomes an accounting problem rather than an engineering one.
The cheaper path is to treat tax as a data contract from the start. Name the four parts of that contract, verify each one on every order path the system has (cart, draft, POS, payment link), and treat the nexus list as maintained data, not a one-time setting.
Who owns tax correctness?
When you scope a commerce build for the US market, you are not deciding whether to connect a tax provider. You are deciding who owns the data flows that keep tax correct across every order surface, and what happens when a state adds a nexus or a draft order bypasses the cart. If that ownership is not explicit, the platform will collect tax correctly on the happy path and quietly get it wrong everywhere else.
We have seen this on enough projects that it is a pattern, not an outlier. The eight commits in ten days were not a bad month. They were the normal cost of a data problem that was never scoped as one.
