About the Tax Groups API

The Tax Groups API lets you create and manage tax groups to categorize products by distinct tax treatments. Use it together with the Tax Regions 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:

• Query Tax Groups returns only the custom tax groups a site created. It doesn't return Wix's built-in default groups, such as Products and Shipping and delivery. To retrieve those, call List Default Tax Groups, or List Default Tax Groups By App IDs for specific apps. Overlooking this is the most common mistake when looking up a group ID, for example when trying to find the shipping group.
• Default (system) tax groups are provided by installed apps and can't be modified or deleted. Products with no taxGroupId automatically use the default group for their vertical.
• A tax group carries no rate. Creating a group doesn't set a rate. The rate lives in a per-region manual tax mapping. A product joins a group through the product's taxGroupId.

Assigning a tax group to products

The link between a product and a tax group is the product's taxGroupId in the Wix Stores catalog. Set it with the Wix Stores Catalog V3 Products API. For example, Bulk Update Products By Filter sets taxGroupId on the matched products and returns a jobId (the update is asynchronous).

taxGroupId is available only in catalog V3. On a catalog V1 store, the V3 Products API returns 404 and V1 has no taxGroupId field. Check the catalog version first and, for V1 stores, route the merchant to the dashboard or to the V3 migration path.

Categories that often need a custom tax group

Some product categories are taxed differently across jurisdictions and usually warrant their own tax group: alcohol, tobacco, digital goods, medications and supplements, clothing and apparel, cannabis and CBD, and prepared food.

Use cases

• Create a new tax group for back-to-school items

Terminology

• Tax group: A group of products that share the same tax treatment. Assign a tax group to products by setting the product's taxGroupId in the Wix Stores catalog.
• Default tax group: A predefined tax group provided by an app, for example Wix Stores. It's the default tax group automatically assigned to products imported from that app's catalog and can't be modified or deleted.