Taxes - Spree Commerce documentation

Overview

Tax is the part of commerce most likely to differ from what you assumed. A US shopper expects $17.99 on the shelf and a little more at the till. A German shopper expects €17.99 to be the whole story, VAT already inside it. Both are correct, and a store selling to both has to do both. Spree handles this by keeping three things separate:

What is being sold — a tax category groups products taxed the same way
Where the customer is — their market and shipping address
Who works out the number — Spree’s own rates, or an external tax service

The result of all this is a set of tax lines on the order — one per charge, recording what was taxed and at what rate. This page is about how they get their numbers.

Tax categories

A tax category is how you say “these things are taxed alike”. Children’s clothing, books and hot food are treated differently from general goods in many countries, and a tax category is where that distinction lives. Every product carries one. If you don’t choose, the default is used.

Field	Description	Example
`name`	What it’s called	`Standard`, `Reduced`, `Digital`
`is_default`	Used by products that don’t pick one	`true`
`tax_code`	The code your tax service knows it by	`1257L`

const reduced = await adminClient.taxCategories.create({
  name: 'Reduced rate',
  tax_code: '1257L',
})

curl -X POST 'https://api.mystore.com/api/v3/admin/tax_categories' \
  -H 'X-Spree-API-Key: sk_xxx' \
  -H 'Content-Type: application/json' \
  -d '{ "name": "Reduced rate", "tax_code": "1257L" }'

tax_code matters once you connect an external service — it is how you tell that service what kind of thing this is, in the vocabulary it already uses.

Tax rates

A tax rate is the number itself, plus where it applies. Whether it is already in the price is the market’s choice, not the rate’s.

Field	Description	Example
`name`	What appears on the invoice	`VAT 20%`
`amount`	The rate as a decimal	`0.2` for 20%
`country_code` / `state_code`	Where it applies	`DE`, or `US` + `CA`
`tax_category`	What it applies to	`Standard`

const { data: rates } = await adminClient.taxRates.list()

await adminClient.taxRates.create({
  name: 'VAT 20%',
  amount: '0.2',
  country_code: 'GB',
  tax_category_id: 'taxcat_xxx',
})

# List tax rates
curl 'https://api.mystore.com/api/v3/admin/tax_rates' \
  -H 'X-Spree-API-Key: sk_xxx'

# Create one
curl -X POST 'https://api.mystore.com/api/v3/admin/tax_rates' \
  -H 'X-Spree-API-Key: sk_xxx' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "VAT 20%",
    "amount": "0.2",
    "country_code": "GB",
    "tax_category_id": "taxcat_xxx"
  }'

Rates name their country and state by ISO code, not by an ID — DE, US + CA. There’s no separate region record to create first.

Included or added on

A market’s tax_inclusive setting is the single most consequential setting here, so it’s worth being precise about what it does.

Added on (US style)
Included (EU style)

The shelf price is what the product costs. Tax is worked out at checkout, once the address is known, and added.A $17.99 item at 5%:


Price shown	$17.99
Tax added	$0.90
Customer pays	$18.89

Set tax_inclusive: false on the market.

The shelf price is the whole price. The tax inside it is shown for information — the customer pays the number they saw.A £17.99 item at 20% VAT:


Price shown	£17.99
VAT inside it	£3.00
Customer pays	£17.99

Set tax_inclusive: true on the market.

When building an order summary, add additional_tax_total only. included_tax_total is already inside the item prices — adding it counts the tax twice. This is the most common bug in a European storefront.

Because prices are shown before anyone knows where the shopper lives, each Market declares whether its prices are quoted with tax included, and that holds for every customer of the market wherever they are. That’s what lets a catalogue page show honest prices to a German visitor and a US visitor at the same time.

Tax lines

Whatever works out the tax, the record is the same: a tax line per charge, saying what was taxed and how.

Attribute	Description
`label`	What the customer sees — `VAT 20%`
`rate`	The rate applied — `"0.2"`
`included`	Whether the tax was already inside the displayed price
`amount` / `display_amount`	The tax charged
`line_item_id` / `fulfillment_id` / `fee_id`	What was taxed — exactly one is set
`return_line_item_id` / `claim_line_item_id` / `exchange_line_item_id`	After the sale: the return, claim or exchange line the tax belongs to
`credit`	`true` for tax given back on a return, claim or exchange

const { data: taxLines } = await adminClient.orders.taxLines.list('or_xxx')

curl 'https://api.mystore.com/api/v3/admin/orders/or_xxx/tax_lines' \
  -H 'X-Spree-API-Key: sk_xxx'

Tax lines attach to a line item, a fulfillment, or a fee — so tax on goods and tax on delivery stay separately visible, which is what a tax return needs. Each line also keeps its own copy of the rate and label. If someone edits that tax rate next year, the order still says what the customer was actually charged. You never create tax lines yourself; they’re written whenever the total is worked out.

Tax given back

When a customer returns something, the tax they paid on it goes back with the money. That tax is recorded as tax lines too, marked credit, on the return, claim or exchange line rather than the order line. Each one names the sale’s tax line it gives back (original_tax_line_id, Admin API), keeps that line’s rate and label, and covers only the units that came back. They never change the order’s own tax totals, and the order’s tax lines list above shows only what was charged.

When tax is worked out

Tax is recalculated whenever the answer could have changed — an item added, an address entered, a delivery option chosen. Every one of those requests returns the updated cart, so a storefront never needs a separate “refresh the tax” call.

Before an address is known

Prices are shown using the market’s tax treatment. For an inclusive market the displayed price is the real one; for an added-on market tax simply hasn’t been worked out yet.

Once the shipping address is entered

The address decides the real rate. Tax lines are written against each item, the delivery charge, and any taxable fee.

At completion

Whatever the tax is at that moment is what’s charged, and the order keeps it. A rate change next month does not rewrite an order from last month.

Connecting a tax service

Spree’s built-in rate tables are fine when the rules are simple — one country, or a handful of clearly-defined rates. They become a liability where the rules are not: US sales tax varies by city and changes constantly, and cross-border EU VAT has thresholds that shift with your turnover. For those, connect a real tax service. The provider is chosen per Market, which means one store can use its own rates in a simple market and an external service in a complicated one.

const { data: providers } = await adminClient.taxProviders.list()

curl 'https://api.mystore.com/api/v3/admin/tax_providers' \
  -H 'X-Spree-API-Key: sk_xxx'

A provider declares up front what it cannot do — no US local tax, no reverse charge — so the dashboard can warn a merchant who pairs it with a market that needs it, rather than quietly under-collecting. Whichever provider is in use, the result is the same: tax lines on the order, in the same shape. Your storefront code doesn’t change. Spree tells the provider whether the market’s prices include tax: estimate and estimate_replacement receive it as tax_inclusive:. A provider passes it on to its service, such as a “tax included” flag on each line, and marks its tax lines included to match. The provider also decides the tax given back on returns, claims and exchanges, and the refund pays exactly what it answers. Spree’s own rates give back each returned unit’s share of the tax the sale actually charged, so the customer gets back what they paid even if a rate has been edited since. An external service may calculate it itself instead, for example at the rates in force on the day of the sale. If it cannot be reached, the return is refused until it can, rather than refunding tax nobody worked out. If you are writing a provider, these are the calls Spree makes after the sale:

Method	When	What it does
`estimate_refund`	A return, claim or exchange opens, and again before its money moves	Writes the credit tax lines the refund will carry
`estimate_replacement`	An exchange opens and is fulfilled	Taxes the replacement as a new sale
`refund`	After the money has moved	Files the credit with your service — no more than the credit lines hold
`commit_replacement`	After an exchange is fulfilled	Files the replacement sale

estimate_refund and estimate_replacement have no default — a provider without them cannot open a return, claim or exchange. To give back exactly what the sale charged, as Spree’s own rates do, answer estimate_refund with Spree::TaxProvider::RecordedShare:

server/app/models/my_app/tax_provider.rb

def estimate_refund(order, items, amounts: nil, tax_date: nil)
  Spree::TaxProvider::RecordedShare.new(order: order, items: items, amounts: amounts).call
end

refund and commit_replacement are optional: by default they do nothing, which suits a service that keeps no record of sales.

Tax-exempt customers

Business customers are often exempt, and the paperwork is real. Spree records a customer’s or company’s tax identifier — a VAT number, an ABN — and can validate it. Companies can also hold exemption certificates, scoped to the country or state that issued them. Exemption is decided when tax is worked out, not stored as a flag on the customer, so an expired certificate stops applying by itself. See Companies. Each certificate points at one of the store’s tax exemption reasons — a list the merchant manages, like return and refund reasons. The tax service receives the reason’s code. A tax service that decides exemptions by code declares the codes it understands, and the dashboard offers them when a merchant adds a reason. See Exemption reasons.

Order totals — how tax rolls into what a customer pays
Markets — where tax treatment and provider are chosen
Returns, exchanges and claims — how tax goes back with a refund
Addresses — what determines the rate
Companies — B2B tax identifiers and exemptions

​Overview

​Tax categories

​Tax rates

​Included or added on

​Tax lines

​Tax given back

​When tax is worked out

​Connecting a tax service

​Tax-exempt customers

​Related

Overview

Tax categories

Tax rates

Included or added on

Tax lines

Tax given back

When tax is worked out

Connecting a tax service

Tax-exempt customers

Related