About the Tax Regions API
The Tax Regions API allows you to create and manage tax regions to apply different tax treatment based on location. Use the Tax Regions API together with the Tax Groups API and the Tax Calculation API to customize the application of tax for your business.
Before you begin
It's important to note the following before starting to code:
- A tax region requires an
appId
for an available tax calculator. Use List Tax Calculators to retrieve a list of available tax calculators for a site.
Use case
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.
Sample Flow
This article shares a possible use case your app could support, as well as a sample flow that could support the use case. This can be a helpful jumping off point as you plan your app's implementation.
Start charging tax in a new region
When a business starts expanding its operations it needs to start charging tax in that new region.
To create a new tax region:
- Use Create Tax Region to create a new tax region to charge tax for.
- Use Tax Calculation Integration SPI to calculate tax, or, in Tax Settings in the Wix dashboard, select the new region and set the tax rate to apply for all existing tax groups.
Tax Regions: Supported Filters and Sorting
The following table shows field support for filters and sorting for the tax region object:
Field | Supported Filters | Sortable |
---|---|---|
id | $eq , $ne , $exists , $in , $hasSome , $startsWith | Sortable |
country | $eq , $ne , $exists , $in , $hasSome , $startsWith | Sortable |
subdivision | $eq , $ne , $exists , $in , $hasSome , $startsWith | Sortable |
appId | $eq , $ne , $exists , $in , $hasSome , $startsWith | Sortable |
createdDate | $eq , $ne , $exists , $in , $hasSome , $lt , $lte , $gt , $gte | Sortable |
updatedDate | $eq , $ne , $exists , $in , $hasSome , $lt , $lte , $gt , $gte | Sortable |
A tax region uses a location to define a specific tax treatment.
A location is defined by country
and subdivision
. The tax region also
dictates whether or not tax is included in the displayed price.
This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Creates a tax region.
Tax regions require a tax calculator appId
. Use
List Tax Calculators
to retrieve a list of available calculators for a site.
Wix uses tax regions to calculate tax.
Permission Scopes
For app development, you must have one of the following permission scopes:This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Retrieves a tax region.
Permission Scopes
For app development, you must have one of the following permission scopes:This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Deletes a tax region.
When a tax region is deleted, tax is not calculated and zero tax will be returned for addresses in this region.
Permission Scopes
For app development, you must have one of the following permission scopes:This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Updates a tax region.
Each time the tax region is updated, revision
increments by 1.
The current revision
must be passed when updating the tax region.
This ensures you're working with the latest tax region and prevents
unintended overwrites.
Permission Scopes
For app development, you must have one of the following permission scopes:This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Retrieves a list of tax regions, given the provided paging, filtering, and sorting.
For field support for filters and sorting, see Tax Regions: Supported Filters and Sorting.
To learn about working with Query endpoints, see API Query Language, Sorting and Paging, and Field Projection.
Permission Scopes
For app development, you must have one of the following permission scopes:This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Permission Scopes
For app development, you must have one of the following permission scopes:This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Triggered when a tax region is updated.
Permission Scopes
For app development, you must have one of the following permission scopes:This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Triggered when a tax region is deleted.