About the Tax Groups API

The Tax Groups API allows you to create and manage tax groups to categorize products based on distinct tax treatments. Use the Tax Groups API together with the Tax Regions API and the Tax Calculation API to customize the application of tax for your business.

Use case

Terminology

  • Tax group: A group of products that share the same tax treatment. Assign tax groups manually to your products with Update Product.
  • Default tax group: A predefined tax group provided by an app, for example Wix Stores, and is the default tax group automatically assigned to products imported from that app's catalog.
Did this help?

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.

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

Many jurisdictions implement back-to-school sales tax holidays before the start of the school year. During these periods certain school supplies, clothing and electronics are exempt from sales tax.

Create a tax group to categorize these items:

  1. Use Create Tax Group to create and name a new tax group. Save the id that is returned. Note that each tax group is calculated based on the tax region, if the tax group is treated differently based on the region then a unique group should be created for each region.
  2. Use Update Product to update the taxGroupId field for the relevant products in your catalog.

When a tax group is no longer needed, for example if the seasonal status no longer applies, simply delete the group. The default tax group for that catalog will apply to any products that have the deleted taxGroupId.

Did this help?

Tax Groups: Supported Filters and Sorting

The following table shows field support for filters and sorting for the tax group object:

FieldSupported FiltersSortable
id$eq, $ne, $in,Sortable
name$eq, $ne, $in,Sortable
createdDate$eq, $ne, $exists, $in, $hasSome, $lt, $lte, $gt, $gteSortable
updatedDate$eq, $ne, $exists, $in, $hasSome, $lt, $lte, $gt, $gteSortable
Did this help?

Tax Group Object

A tax group is a category of specific line items grouped together based on their tax treatment. You can create new tax groups to apply distinct tax rates and rules.

Properties
idstringRead-onlyformat GUID

Tax group ID.

namestringminLength 1maxLength 200

Tax group name.

revisionintegerformat int64

Revision number, which increments by 1 each time the tax group is updated. To prevent conflicting changes, the current revision must be passed when updating the tax group.

Ignored when creating a tax group.

createdDatestringRead-onlyformat date-time

Date and time the tax group was created.

updatedDatestringRead-onlyformat date-time

Date and time the tax group was last updated.

Did this help?
POST

Create Tax Group

Developer Preview

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 group.

Add the taxGroupId to specific products to categorize a group based on distinct tax treatment. Wix uses tax groups to calculate tax.

In addition to tax groups you create, default tax groups are already included in all Wix catalogs. Use List Default Tax Groups to retrieve them. You can also use the Tax Groups Integration Service Plugin to create new default tax groups that can be applied directly to an entire catalog of products.

Authentication

You can only call this method when authenticated as a Wix app or Wix user identity.

Permissions
Manage Stores - all permissions
Manage Orders
Manage Restaurants - all permissions
Learn more about app permissions.
Endpoint
POST
https://www.wixapis.com/billing/v1/tax-groups
Body Params
taxGroupTaxGroupRequired

Tax group to create.

Response Object
taxGroupTaxGroup

Created tax group.

Create TaxGroup

Creates a TaxGroup with basic info

Request
cURL
curl --location 'https://www.wixapis.com/billing/v1/tax-groups' \
--header 'accept: application/json, text/plain, */*' \
--header 'accept-language: en-US,en;q=0.9' \
--header 'authorization: <AUTH>' \
--header 'content-type: application/json' \
--data '{
  "tax_group": {
    "name": "perfumes"
  }
}'
Response
JSON
{
  "taxGroup": {
    "id": "fec40cc5-28c7-4c53-a29b-2f5eed1c614d",
    "name": "perfumes",
    "revision": "1",
    "createdDate": "2024-02-06T11:08:29.497Z",
    "updatedDate": "2024-02-06T11:08:29.497Z"
  }
}
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Event TriggersThis method triggers the following events:
Tax Group Created
Did this help?
GET

Get Tax Group

Developer Preview

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 group.

Permissions
Manage eCommerce - all permissions
Manage Stores - all permissions
Manage Orders
Manage Restaurants - all permissions
Learn more about app permissions.
Endpoint
GET
https://www.wixapis.com/billing/v1/tax-groups/{taxGroupId}
Path Params
taxGroupIdstringRequired

ID of the tax group to retrieve.

Response Object
taxGroupTaxGroup

Retrieved tax group.

Get TaxGroup

Get a TaxGroup by id

Request
cURL
curl --location 'https://www.wixapis.com/billing/v1/tax-groups/fec40cc5-28c7-4c53-a29b-2f5eed1c614d' \
--header 'accept: application/json, text/plain, */*' \
--header 'accept-language: en-US,en;q=0.9' \
--header 'authorization: <AUTH>' \
--header 'content-type: application/json' \
Response
JSON
{
  "taxGroup": {
    "id": "fec40cc5-28c7-4c53-a29b-2f5eed1c614d",
    "name": "perfumes",
    "revision": "1",
    "createdDate": "2024-02-06T11:08:29.497Z",
    "updatedDate": "2024-02-06T11:08:29.497Z"
  }
}
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?