Who this is for. Developers and administrators setting up tax for a store. After this page you can choose and connect a provider, send addresses to the right one, map products to the provider's tax codes, and decide whether prices include tax.
One shape for tax and shipping
Tax and shipping answer the same two questions about every line: what is it, and where is it going. Each sorts products into categories of its own, and each decides by an address:
| Tax | Shipping | |
|---|---|---|
| What the product is | Its tax category | Its shipping category, or the Default shipping category |
| Where it is going | A tax zone matching the address chooses the provider; an address in no zone goes to the Default provider | Each shipping method's template reads the delivery address and creates rates for the places the method serves |
| What sets the amount | The provider, from the tax code mapped to the category | The method's template, with rates.create() |
| Set up in | The Taxes settings, tax providers, tax zones and tax categories | The Shipping settings, shipping categories, groups and shipping methods |
The rest of this page is tax. Shipping is on Shipping methods and their templates.
How a checkout's tax is worked out
Tax is calculated by a provider: a service that holds the rates and rules for each jurisdiction. There are three provider types:
| Type | What it is | Its settings |
|---|---|---|
| Avalara | Avalara's tax service | Account ID, License Key, Company, Sandbox, Submit Documents, Validate Address, Default Item Tax Code, Shipping Tax Code |
| Stripe Tax | Stripe's tax service | Connected Account ID (left blank, the account of the site's Stripe payment method), Test Mode, Submit Documents, Default Item Tax Code, Shipping Tax Code |
| MockTax | One flat percentage on every line, for development and testing | Tax Rate |
A provider takes part only while its Enabled switch is on. For each checkout:
- Tax is calculated while the Enabled switch in the Taxes settings (
Taxes.enabled) is on. - Zone resolves to (
Taxes.zoneAddress) picks the address to tax by: Shipping address (the default), Billing address or Warehouse address. - A tax zone with a location matching that address chooses the provider. An address that matches no zone is taxed by the Default provider (
Taxes.fallbackProvider, required). - The provider receives the lines, the shipping, the destination and the origin, which is the Default warehouse (
Taxes.defaultWarehouse, required): "Warehouse used for tax calculations as origin address when no warehouse is specified". It returns the tax, which is stored on the checkout's lines and shipping rate. - With the provider's Submit Documents on, the purchase is recorded with the provider for its tax reports; with it off, the provider only calculates.
The checkout asks the provider again whenever something that affects the tax changes: the lines, the selected shipping rate, the delivery address, the person's email or the totals. Tax is part of the checkout's amounts, so it is in the checkout's currency (Its currency, and the language of its lines), and it moves to the order and its invoice with them.
Tax zones
A tax zone has a Provider and one or more locations. A location restricts the zone to a place:
| Field | What to enter |
|---|---|
| Country code | The country, as the checkout's address names it: Australia, New Zealand |
| State | Optional. The state, as the address names it: Victoria. Empty matches every state. |
| Postcode | Optional. The postcode exactly: 3065. Empty matches every postcode. |
A checkout's address carries the country and state by name, as they are written to the checkout (Writing the email and addresses), and each location field must match the address exactly. Where several locations match, a postcode match is chosen over a state match, and a state match over a country match. Only zones whose provider is enabled take part.
A store that uses one provider everywhere needs no zones: make that provider the Default provider and it taxes every address. Zones are for sending different places to different providers, such as one provider for domestic sales and another for exports.
Tax categories and provider codes
A tax category says what a product is for tax: clothing, food, digital goods. It has a name, a Code ("A short, unique code that identifies the tax category. Unlike the name, it never changes.") and a Description, and it is set on the product. Each provider's Category Codes map every tax category to that provider's own code, its Tax Service Code. Items without a tax category take the provider's Default Item Tax Code, and shipping takes its Shipping Tax Code.
Because the mapping lives on the provider, a store that moves to another provider maps the same categories to the new provider's codes, and its products keep their categories. Integrations list the categories with GET /cdna-api/taxes/categories (Taxes API reference).
Prices that include tax
Whether the store's prices already include tax is one switch for the whole client, Pricing includes tax (Taxes.pricingIncludesTax, off by default): "Determine whether tax is included in pricing. This does not remove existing tax values from products." It is sent to the provider with every calculation, so the provider reads the amounts the way the store priced them: to Avalara as each line's taxIncluded, and to Stripe Tax as the tax_behavior (inclusive or exclusive) of each line and of the shipping.
Set it once, before launch, to match how prices are entered. A store selling to consumers where prices are quoted with GST or VAT usually enters them with tax; a store selling to businesses usually without. Label the catalogue's prices the same way (Prices and tax). Then place test orders through the provider's sandbox and compare each order's lines, tax total and total with the provider's own record of the calculation, as on Testing tax and shipping.
What a provider takes over
With a provider enabled, the rates, the rules for each jurisdiction and, with Submit Documents on, the record for tax returns are the provider's. What stays with the store:
- The provider account and its credentials. Avalara's License Key is updated here whenever a new one is generated in the Avalara account, as its help says.
- The tax categories on the products, their mapping to the provider's codes, and the two default codes.
- Avalara's Validate Address. On, the destination address is validated, and an address that fails validation cannot be purchased; off, Avalara may estimate from a partial address. Its help explains the trade-off.
- Planning for the provider's availability, below.
When a provider cannot be reached
A checkout with tax asks its provider at every change that alters the tax, so the provider's answer is part of each of those steps. If the provider does not answer, that request answers with an error, and the shopper can repeat the step once the provider is back. Plan for it:
- Press Test connection on the provider after every change of credentials. It answers "Connection to the provider was successful".
- Develop and test against the provider's own sandbox (Avalara's Sandbox, Stripe Tax's Test Mode), never the live account.
- Watch the provider's status page, and subscribe to its incident notices, from launch day on.
- On the checkout page, answer an error from the shipping and address calls with a message and a way to try again, so the shopper is never left at a dead end.
Shipping, and testing both
Every shipping method is a template that creates its own rates: see Shipping methods and their templates.
What a method needs before it offers a rate, as a checklist in the order to check it: see Making a shipping method appear at checkout.
Running tax and shipping end to end without charging anyone is on Testing tax and shipping.