Tax rates are percentages a store uses to calculate taxes due for products and services. Tax zones are geographic regions defined in a store. Tax zones allow you to apply different tax rates to different customer groups and locations. All the tax rates and zones you configure for a store are available on each storefront.
This guide demonstrates how to use the Tax Rates and Zones API. The Tax Rates and Zones API allows you to configure manual taxes for a store. For more information, see the Tax Rates and Zones API Reference.
A zone must be defined by one of the following location parameters:
You can further narrow the scope of a zone by specifying one or more customer groups to whom the zone applies. You can also use zones to choose how a store displays prices to different customer groups; for example, whether prices are inclusive or exclusive of tax.
The default tax zone, which has a zone id of 1, covers locations that other zones don’t cover. Shoppers who don’t meet the criteria for any manually-defined tax zone fall under the default tax zone. You cannot disable or delete the default tax zone. When updating the default tax zone, you cannot adjust the locations or customer groups that it covers.
To add tax zones to a store, send a request to the Create tax zones endpoint. The following example creates a subdivision-based zone.
The response includes an id for each tax zone. Use the id to get, update, or delete a specific tax zone.
To modify a tax zone, send a request to the Update tax zones endpoint. In the request body, specify the id of the zones you want to update. The request updates only the fields for which you supply values.
shopper_target_settings for the default tax zone.locations cannot be an empty array in the request body.Get tax zones returns all tax zones by default. To return select tax zones, include the id:in query parameter.
To delete tax zones, send a request to the Delete tax zones endpoint. Use the id:in query parameter to specify the tax zones you want to delete. Deleting a tax zone cascades to remove all associated tax rates.
After creating a zone, you can add rates to the zone. You can add multiple rates to a zone to help the store collect and report taxes to one or more taxation authorities. You can add a rate for each tax class in your store.
To create tax rates, send a request to the Create tax rates endpoint. Specify the rate name, rates of each tax class, and the associated tax zone. The tax_zone_id is the id received from calls to the Get tax zones endpoint.
The response includes an id for each tax rate. Use the tax rate id to get, update, or delete the associated tax rate.
To update tax rates, send a request to the Update tax rates endpoint. In the request body, specify the id of the rates you want to update. The tax_zone_id is the id received from calls to the Get tax zones endpoint.
To get tax rates, send a request to the Get tax rates endpoint. To get the tax rates for a subset of zones, pass a comma-separated string of the tax zone ids using the tax_zone_id:in query parameter.
To delete tax rates, send a request to the Delete tax rates endpoint. Use the id:in query parameter to specify the tax rates you want to delete.