About the Tax Regions API

The Tax Regions API lets you create and manage tax regions to apply different tax treatment based on location. Use it together with the Tax Groups API, the Manual Tax Mappings API, and the Tax Calculation API to customize how tax is applied for a business.

Before you begin

It's important to note the following points before starting to code:

• Resolve the calculator appId dynamically. A tax region requires an appId for an available tax calculator. Call List Tax Calculators to retrieve the calculators for a site. Never hardcode the appId, because calculator app IDs are installation-scoped and can differ between sites.
• country and subdivision are ISO codes, not display names. country is an ISO 3166-1 alpha-2 code (for example, US). subdivision is an ISO 3166-2 code without the country prefix (for example, NY). Storing a full name such as Georgia instead of GA silently results in no tax being charged. No display names are stored, so you're responsible for translating codes to names.
• Subdivisions are supported only for some countries. You can create subdivision-level regions for AU, BR, CA, FR, DE, IN, IT, MX, NL, PT, ES, AE, GB, and US. For any other country, create the region at the country level by omitting subdivision or setting it to *.

Choosing a tax calculator

Each tax region is bound to one tax calculator, identified by its appId:

• Wix manual tax calculator: the built-in calculator. You set its rates with the Manual Tax Mappings API.
• Avalara: automatic sales-tax calculation. Connecting Avalara is done in the Wix dashboard and requires a Premium plan that supports automated sales tax; there's no API to enable it. The tax API can only list Avalara as an available calculator and bind a region to its appId. Avalara automatic tax is unavailable in Brazil, India, Puerto Rico, and several other territories; for those locations, use the Wix manual tax calculator instead.

Use cases

• Start charging tax in a new region

Terminology

• Tax calculator: An app that is used under the hood to calculate tax for a Wix site. The app calculates tax based on the tax group of the product and the tax region of the sale. A site assigns each tax region to the Wix manual tax calculator or an external calculator app to properly calculate tax.
• Wix manual tax calculator: The default tax calculator installed with a Wix site. The tax rates to apply for this calculator can be manually adjusted in the Tax Settings in the Wix dashboard.