Tax codes on Shopify orders
Lesson 9 of 18 8 min read
Make sure reduced-rate and standard-rate lines get the right tax code, and know when to force a tax code instead.
Tax is where a Shopify integration most often looks right but isn't. An order can arrive with the correct totals and still post a 5% line as 20% in your accounts. In this lesson you'll learn why that happens and how to set up tax codes so each rate lands on its own code.
The problem: Shopify titles every rate the same
Shopify gives every tax line for a country the same title, whatever the rate. A UK order
labels both a 20% line and a 5% line GB VAT. Supply Lens looks up the tax code for each
line using identifiers, and by default it uses the title and the UNCL5305 category
code (an international code: S for a line with tax, Z for one without). With those
defaults, both lines resolve to the same tax code, and the reduced-rate line is treated as
standard rate.
The fix: add the rate to the identifier
| taxCodeIdentifiersByCountry | For each country, which identifiers are used to find the tax code for goods lines. Default for every country: shopify-tax-code-title and uncl5305-code. |
|---|---|
| shippingTaxCodeIdentifiersByCountry | The same choice for shipping lines. Default for every country: shopify-tax-code-title and uncl5305-code. |
You can choose any combination of these identifiers per country:
| Value | Example |
|---|---|
uncl5305-code | S for a line with tax, Z for one without |
shopify-tax-rate | 5% |
shopify-tax-country-rate | GB 5% |
shopify-tax-code-title | GB VAT |
shopify-tax-code-title-rate | GB VAT 5% |
The rate-qualified forms (the ones with a percentage) are what let each rate find its own tax code. A typical set-up changes only the UK and leaves everything else on the default:
{
"default": ["shopify-tax-code-title", "uncl5305-code"],
"values": { "GB": ["shopify-tax-code-title-rate", "shopify-tax-country-rate"] }
}
Rules worth knowing
- Each identifier widens the match. A tax code entry is a candidate if it matches any identifier you list. Where several match, the most specific entry wins: organisation-specific ahead of shared, country-specific ahead of country-agnostic, then the entry's order. There's no error on a tie, so point all the forms you configure at the same tax code rather than relying on one to beat another.
- Drop
uncl5305-codewhen you add a rate form. It matches the shared standard-rate entry, which would then compete on every line whatever its rate. - Zero-rated lines are unaffected. A line with no tax always resolves on the UNCL5305
code
Z. - Missing pieces are skipped. An identifier that can't be built is skipped, such as a
country form on an order with no address. If nothing is left,
uncl5305-codeis used so there's always something to resolve on. - Percentages show at most four decimal places, such as
17.5%or8.25%.
Set up the code list first
Before you add a rate-qualified form for a country, your tax code list must have an entry
for every combination it will produce. A combination with no entry leaves the tax code
unresolved, and anything that reads a value from it writes an empty value rather than
failing. shopify-tax-country-rate (GB 20%, GB 5% and so on) is the lower-maintenance
option if your tax line titles aren't consistent.
Which country?
The country is worked out per line, following where the line is taxed:
- Physical goods use the delivery address, falling back to billing. A line with no "requires shipping" flag is treated as physical goods.
- Digital goods use the billing address, falling back to delivery.
- Order-level tax, such as discounts and duties, uses the delivery address.
- Shipping lines use the delivery address, falling back to billing.
Why shipping is separate
Shopify charges shipping tax at a blended rate based on the mix of goods in the order, so
the rate shown on a shipping line is nominal. It can read 20% while the amount charged
works out at zero. Adding that rate to the identifier would find a tax code the order
never used. That's why shipping keeps the title and S/Z default even when goods lines
are rate-qualified.
When not to use rate forms
Keep the default for countries that charge several taxes per line. A US order carries separate state, county, city and district tax lines, and you'd need a code list entry for every combination.
Forcing a tax code
Sometimes you want one tax code regardless of what Shopify says, for example a store that only sells zero-rated goods. These settings override the automatic choice:
| forceTaxCode | A tax code applied to the whole order. |
|---|---|
| forceLineTaxCode | A tax code applied to every product line. |
| forceAdjustmentTaxCode | A tax code applied to every discount and charge adjustment. |
| forceShippingTaxCode | A tax code applied to every shipping line. |
Hilltop Coffee's reduced-rate line
Hilltop sells coffee beans (zero-rated) and branded mugs (standard rate), plus a
reduced-rate product. In testing, Priya sees the reduced-rate line posted at 20% in
Unleashed. She asks her accountant to add GB VAT 5% and GB VAT 20% entries to the tax
code list, plus GB 5% and GB 20%, all pointing at the right codes. Then she sets the
UK identifiers to shopify-tax-code-title-rate and shopify-tax-country-rate, dropping
uncl5305-code. The beans still resolve on Z. She makes the same change on the shipment
Configuration, because the shipment setting should normally be kept in step with the
order one.
Recap
- Shopify titles every rate in a country the same, so by default a 5% line can be coded as 20%.
- Add rate-qualified identifiers per country, and drop
uncl5305-codewhen you do. - Create code list entries for every combination before switching on.
- Shipping has its own setting and usually stays on the default.
- Use the force settings to apply one tax code regardless of Shopify's tax lines.
Quick guides for this topic
Your progress is saved in this browser. Create a free account to keep it everywhere, take quizzes and earn certificates.