1. The rate comes from the destination
A merchant configures a rate per destination. When an order is priced, the most specific match wins:- the customer’s country and region (a US state, a Canadian province)
- the customer’s country — the shape every EU member state uses
- the merchant’s
Othercatch-all row, if they have set one - otherwise no tax
The merchant’s per-destination rates are not exposed on the App API. Read the
tax your app needs from the order or cart totals rather than trying to
reconstruct it.
2. Inclusive pricing does not move the total
GET /api/v1/settings/taxes returns productPrices, which is either
ExclusiveOfTax or InclusiveOfTax. This is a store-wide setting and it
changes what the tax figure means:
A €149 product at 19% carries €23.79 of tax when prices are inclusive, and
the customer pays €149.00. The same product at the same rate carries
€28.31 when prices are exclusive, and the customer pays €177.31.
Consumer sales in the EU and the UK require the advertised price to be the price
paid, so stores selling there run inclusive. An app that assumes tax is always
added on top will over-state every total on those stores by the tax amount.
The trap
Applying the exclusive formula to an inclusive price does not just misplace the tax — it produces a larger number, because it charges tax on a price that already contains tax. Always branch onproductPrices; never infer it from the
figures.
Where the tax appears
- Orders API —
tax_priceon the order, andtax_lines[]on each line item. - Order records — the tax calculated when the order was placed is stored with it. Changing a rate afterwards never re-prices an existing order.
What is not supported yet
- B2B reverse charge. A VAT-registered business buyer in another EU country is charged VAT like any other customer; there is no VIES validation step.
- Reduced rates per product. A rate applies to the whole catalogue in that country, so books, food and children’s clothing cannot carry their own rate.