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.
Was this helpful?
Yes
No

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.

Was this helpful?
Yes
No

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
Was this helpful?
Yes
No
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.
Was this helpful?
Yes
No
PostCreate 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. Use can also use the Tax Groups Integration SPI to create new default tax groups that can be applied directly to an entire catalog of products.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Stores - all permissions
Manage Orders
Learn more about permission scopes.
Endpoint
POST
https://www.wixapis.com/billing/v1/tax-groups
Event TriggersThis method triggers the following events:
Tax Group Created
Was this helpful?
Yes
No
GetGet 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.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Stores - all permissions
Manage eCommerce - all permissions
Manage Orders
Learn more about permission scopes.
Endpoint
GET
https://www.wixapis.com/billing/v1/tax-groups/{taxGroupId}
Was this helpful?
Yes
No
DeleteDelete 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.

Deletes a tax group.

If a tax group is deleted but the taxGroupId is still assigned to a product then the default tax group is used to calculate tax.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Stores - all permissions
Manage Orders
Learn more about permission scopes.
Endpoint
DELETE
https://www.wixapis.com/billing/v1/tax-groups/{taxGroupId}
Event TriggersThis method triggers the following events:
Tax Group Deleted
Was this helpful?
Yes
No
PatchUpdate 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.

Updates a tax group.

Each time the tax group is updated, revision increments by 1. The current revision must be passed when updating the tax group. This ensures you're working with the latest tax group and prevents unintended overwrites.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Stores - all permissions
Manage Orders
Learn more about permission scopes.
Endpoint
PATCH
https://www.wixapis.com/billing/v1/tax-groups/{taxGroup.id}
Event TriggersThis method triggers the following events:
Tax Group Updated
Was this helpful?
Yes
No
PostQuery Tax Groups
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 list of tax groups, given the provided paging, filtering, and sorting.

Only tax groups that were created by this site will be retrieved with this query. Use List Default Tax Groups or List Default Tax Groups By App ID to retrieve a site's default tax groups.

For field support for filters and sorting, see Tax Groups: 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:
Manage Stores - all permissions
Manage eCommerce - all permissions
Manage Orders
Learn more about permission scopes.
Endpoint
POST
https://www.wixapis.com/billing/v1/tax-groups/query
Was this helpful?
Yes
No
GetList Default Tax Groups
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 list of default tax groups.

The default tax groups for a site are inherited by the apps installed on the site. For example, the Wix Stores app includes a "Products" tax group by default.

Add additional default tax groups with the Tax Groups Integration SPI.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Stores - all permissions
Manage eCommerce - all permissions
Manage Orders
Learn more about permission scopes.
Endpoint
GET
https://www.wixapis.com/billing/v1/tax-groups/default-tax-groups
Was this helpful?
Yes
No
PostList Default Tax Groups By App Ids
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 default tax groups for specific apps.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Stores - all permissions
Manage eCommerce - all permissions
Manage Orders
Learn more about permission scopes.
Endpoint
POST
https://www.wixapis.com/billing/v1/tax-groups/list-default-tax-groups-by-app-ids
Was this helpful?
Yes
No
Tax Group Created
Developer Preview

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

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Stores - all permissions
Manage eCommerce - all permissions
Manage Orders
Learn more about permission scopes.
Event BodyEvent Body Event data is received as a JSON Web Token (JWT). It may be delayed. Be sure to verify the data was sent by Wix.
Event Data
idstring
Unique event ID. Allows clients to ignore duplicate webhooks.
entityFqdnstring
Fully qualified domain name of the entity associated with the event. Expected wix.billing.v1.tax_group.
slugstring
Event name. Expected created.
entityIdstring
ID of the entity associated with the event.
eventTimestringformat date-time
Event timestamp.
triggeredByAnonymizeRequestboolean
Whether the event was triggered as a result of a privacy regulation application (for example, GDPR).
originatedFromstring
If present, indicates the action that triggered the event.
createdEventobject
Event information.
Was this helpful?
Yes
No
Tax Group Updated
Developer Preview

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

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Stores - all permissions
Manage eCommerce - all permissions
Manage Orders
Learn more about permission scopes.
Event BodyEvent Body Event data is received as a JSON Web Token (JWT). It may be delayed. Be sure to verify the data was sent by Wix.
Event Data
idstring
Unique event ID. Allows clients to ignore duplicate webhooks.
entityFqdnstring
Fully qualified domain name of the entity associated with the event. Expected wix.billing.v1.tax_group.
slugstring
Event name. Expected updated.
entityIdstring
ID of the entity associated with the event.
eventTimestringformat date-time
Event timestamp.
triggeredByAnonymizeRequestboolean
Whether the event was triggered as a result of a privacy regulation application (for example, GDPR).
originatedFromstring
If present, indicates the action that triggered the event.
updatedEventobject
Event information.
Was this helpful?
Yes
No
Tax Group Deleted
Developer Preview

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

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Stores - all permissions
Manage eCommerce - all permissions
Manage Orders
Learn more about permission scopes.
Event BodyEvent Body Event data is received as a JSON Web Token (JWT). It may be delayed. Be sure to verify the data was sent by Wix.
Event Data
idstring
Unique event ID. Allows clients to ignore duplicate webhooks.
entityFqdnstring
Fully qualified domain name of the entity associated with the event. Expected wix.billing.v1.tax_group.
slugstring
Event name. Expected deleted.
entityIdstring
ID of the entity associated with the event.
eventTimestringformat date-time
Event timestamp.
triggeredByAnonymizeRequestboolean
Whether the event was triggered as a result of a privacy regulation application (for example, GDPR).
originatedFromstring
If present, indicates the action that triggered the event.
deletedEventstruct
Event information.
Was this helpful?
Yes
No