The Tax Gap Medusa Documents — and How to Fill It

You spin up a Medusa store, set your US tax region, type in a rate, and ship it. Checkout works. Cart adds tax. Looks done.

Then two orders come in. One ships to Chicago, one to Portland, Oregon. Your flat rate charged both of them the same. And it was wrong on both.

That's the catch — and the best part is, Medusa already told you. The docs say it plainly: the built-in tax calculation "will not work for the US or other countries with varying rates within the same region." That's not a bug report. That's an honest seam, drawn on the map, with a sign that says plug something in here.

One flat rate, two wrong answers

Here's why a single "region" rate can't hold up in the US.

Take that Chicago cart. The correct combined sales tax there is 10.25% — Illinois state, plus Cook County, plus the City of Chicago, plus the Regional Transportation Authority, all stacked on the same sale. Set your region to a tidy 6.25% (the Illinois state rate) and you under-collect the local portion. The store still owes that local tax at remittance time. You just didn't collect it. That gap comes out of your margin.

Now the Portland cart. Oregon has no sales tax at all — 0%. Any flat region rate over-charges that customer on a sale that should carry nothing. Less catastrophic than under-collecting, but it's still wrong, it's still on the receipt, and it's the kind of thing that shows up in a chargeback or a one-star review.

Same store. Same flat rate. One destination under-taxed, one over-taxed. The only fix is destination-based rates that know about state and local jurisdictions — and that know whether you even have nexus in the place you're shipping to.

Medusa left the door open. We walked through it.

This is the part I like, because it's not a hack. Medusa's architecture is genuinely clean here. Tax calculation is a provider seam — you register a tax provider that implements getTaxLines, and Medusa hands it the cart's line items and the shipping destination and asks: what tax applies?

The default provider answers with your flat region rate. A better provider can answer with the truth.

So we built one. openaccountants/medusa-tax-demo is a small, open reference integration: a Medusa tax provider that, instead of reading a static number, calls the OpenAccountants MCP for the destination on the cart and returns rates that are destination-correct, nexus-aware, and signed off by a named licensed accountant.

The shape of it is about this simple:

async getTaxLines(items, { shipping_address }) {
  const { rate, breakdown } = await oa.getRates(shipping_address)
  return items.map((i) => ({ ...i, rate, name: breakdown }))
}

Chicago comes back 10.25% with the state/county/city/RTA breakdown attached. Portland comes back 0% because Oregon has no sales tax. Same code path, correct on both — because the answer comes from the destination, not from a field you typed once and forgot.

Why "accountant-signed" is the whole point

Plenty of things can return a number for a US address. The harder question is: who stands behind that number?

For the US rates in this demo, that's Amir Pelinkovic, our US lead. Every rate the provider returns traces back to a rule a named, licensed accountant has verified — not a scraped table, not a model's best guess, not a CSV someone downloaded in 2023. When a county changes its rate or a state tweaks a threshold, the fix lands at the source and flows straight through the MCP into your store. You don't re-key anything.

That's the difference between a tax answer and one you'd actually want on a receipt your customer keeps.

None of this is a knock on Medusa. The opposite. Medusa did the right thing twice: it documented exactly where the built-in calc stops, and it built a provider seam so you can drop in something that goes further. We just filled the gap they were honest enough to flag — and made the thing on the other side of the seam accountant-verified across 190+ jurisdictions, not just the US.

If you run a Medusa store that ships to more than one place, this is worth ten minutes. Clone openaccountants/medusa-tax-demo, run it against a Chicago cart and a Portland cart, and watch the rate land correctly on both. Then connect the OpenAccountants MCP to your own store at openaccountants.com and let your tax lines come from rules a real accountant signed.

Your flat rate was never going to survive a multi-state checkout. Good news: you don't need it to.