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.
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.
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:
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.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
.
The following table shows field support for filters and sorting for the tax group object:
Field | Supported Filters | Sortable |
---|---|---|
id | $eq , $ne , $in , | Sortable |
name | $eq , $ne , $in , | 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 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.
Tax group ID.
Tax group name.
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.
Date and time the tax group was created.
Date and time the tax group was last updated.
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.
You can only call this method when authenticated as a Wix app or Wix user identity.
Tax group to create.
Created tax group.
Creates a TaxGroup with basic info
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"
}
}'
{
"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"
}
}
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.
ID of the tax group to retrieve.
Retrieved tax group.
Get a TaxGroup by id
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' \
{
"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"
}
}
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.
You can only call this method when authenticated as a Wix app or Wix user identity.
ID of the tax group to delete.
Deletes a TaxGroup by its ID
curl --location --request DELETE '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' \
{}
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.
You can only call this method when authenticated as a Wix app or Wix user identity.
Tax group ID.
Tax group info to update.
Updated tax group.
Get a TaxGroup by id
curl --location --request PATCH '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' \
--data '{
"taxGroup": {
"id": "fec40cc5-28c7-4c53-a29b-2f5eed1c614d",
"name": "cosmetics and more",
"revision": "4"
},
"fieldMask": {
"paths": [
"name"
]
}
}'
{
"taxGroup": {
"id": "fec40cc5-28c7-4c53-a29b-2f5eed1c614d",
"name": "cosmetics and more",
"revision": "5",
"createdDate": "2024-02-06T11:08:29.497Z",
"updatedDate": "2024-02-06T11:17:27.057Z"
}
}
There is 1 error with this status code:
See the entire list and learn more about Wix errors.
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.
Query options.
Retrieved default tax groups.
Paging metadata.
Query tax groups
curl --location 'https://www.wixapis.com/billing/v1/tax-groups/query' \
--header 'accept: application/json, text/plain, */*' \
--header 'accept-language: en-US,en;q=0.9' \
--header 'authorization: <AUTH>' \
--header 'content-type: application/json' \
--data '{"query":{"cursorPaging":{},"sort":[{"fieldName":"createdDate","order":"DESC"}]}}'
{
"taxGroups": [
{
"id": "c4323faa-ca42-4444-ae1f-d398bcf098a4",
"name": "tax group number 1",
"revision": "1",
"createdDate": "2024-02-05T12:52:21.967Z",
"updatedDate": "2024-02-05T12:52:21.967Z"
},
{
"id": "56ce0f07-adda-4419-9d16-1af86b2ed284",
"name": "tax group number 2",
"revision": "3",
"createdDate": "2024-02-01T14:27:01.462Z",
"updatedDate": "2024-02-06T08:46:23.178Z"
}
],
"pagingMetadata": {
"count": 2,
"cursors": {},
"hasNext": false
}
}
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 Service Plugin.
Retrieved default tax groups.
Lists all the default tax groups of the apps installed on the site. Current example is for a Wix site with Wix Stores app installed.
curl --location 'https://www.wixapis.com/billing/v1/tax-groups/default-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' \
{
"taxGroups": [
{
"id": "215238eb-22a5-4c36-9e7b-e7c08025e04e",
"name": "Products",
"revision": null,
"createdDate": null,
"updatedDate": null
},
{
"id": "5a5d7b15-5e29-451c-9019-f5065ca7e5e5",
"name": "Shipping and delivery",
"revision": null,
"createdDate": null,
"updatedDate": null
}
]
}
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.
App IDs to retrieve default tax groups for.
Retrieved default tax groups.
Bulk action metadata.
Lists all the default tax groups of the apps installed on the site by the ids provided in the input. Current example is for a Wix site with Wix Stores app installed.
curl --location 'https://www.wixapis.com/billing/v1/tax-groups/list-default-tax-groups-by-app-ids' \
--header 'accept: application/json, text/plain, */*' \
--header 'accept-language: en-US,en;q=0.9' \
--header 'authorization: <AUTH>' \
--header 'content-type: application/json' \
--data '{
"appIds": [
"215238eb-22a5-4c36-9e7b-e7c08025e04e"
]
}'
{
"results": [
{
"taxGroupMetadata": {
"id": "215238eb-22a5-4c36-9e7b-e7c08025e04e",
"originalIndex": 0,
"success": true
},
"taxGroup": {
"id": "215238eb-22a5-4c36-9e7b-e7c08025e04e",
"name": "Products"
}
}
],
"bulkActionMetadata": {
"totalSuccesses": 1,
"totalFailures": 0,
"undetailedFailures": 0
}
}
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.
Unique event ID. Allows clients to ignore duplicate webhooks.
Fully qualified domain name of the entity associated with the event. Expected wix.billing.v1.tax_group
.
Event name. Expected created
.
ID of the entity associated with the event.
Event timestamp.
Whether the event was triggered as a result of a privacy regulation application (for example, GDPR).
If present, indicates the action that triggered the event.
Event information.
The data payload will include the following as an encoded JWT:
{
"data": {
"eventType": "wix.billing.v1.tax_group_created",
"instanceId": "<app-instance-id>",
"data": "<stringified-JSON>",
// The identity field is sent as a stringified JSON
"identity": {
"identityType": "<identityType>", // ANONYMOUS_VISITOR, MEMBER, WIX_USER, APP
"anonymousVisitorId": "<anonymousVisitorId>", // in case of ANONYMOUS_VISITOR
"memberId": "<memberId>", // in case of MEMBER
"wixUserId": "<wixUserId>", // in case of WIX_USER
"appId": "<appId>" // in case of APP
}
}
}
{
"id": "436872ad-59dd-4eb5-ba9a-1782cb2e617f",
"entityFqdn": "wix.billing.v1.tax_group",
"slug": "created",
"entityId": "f7c945f7-180a-4cb4-a27c-17a71e29f908",
"createdEvent": {
"entity": {
"id": "f7c945f7-180a-4cb4-a27c-17a71e29f908",
"name": "sdff",
"revision": "1",
"createdDate": "2024-02-06T07:15:01.806Z",
"updatedDate": "2024-02-06T07:15:01.806Z"
}
},
"eventTime": "2024-02-06T07:15:02.043020952Z",
"triggeredByAnonymizeRequest": false,
"entityEventSequence": "1"
}
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.
Unique event ID. Allows clients to ignore duplicate webhooks.
Fully qualified domain name of the entity associated with the event. Expected wix.billing.v1.tax_group
.
Event name. Expected updated
.
ID of the entity associated with the event.
Event timestamp.
Whether the event was triggered as a result of a privacy regulation application (for example, GDPR).
If present, indicates the action that triggered the event.
Event information.
The data payload will include the following as an encoded JWT:
{
"data": {
"eventType": "wix.billing.v1.tax_group_updated",
"instanceId": "<app-instance-id>",
"data": "<stringified-JSON>",
// The identity field is sent as a stringified JSON
"identity": {
"identityType": "<identityType>", // ANONYMOUS_VISITOR, MEMBER, WIX_USER, APP
"anonymousVisitorId": "<anonymousVisitorId>", // in case of ANONYMOUS_VISITOR
"memberId": "<memberId>", // in case of MEMBER
"wixUserId": "<wixUserId>", // in case of WIX_USER
"appId": "<appId>" // in case of APP
}
}
}
{
"id": "ff2ac8a2-8a59-4dda-b1b4-bde4057b4589",
"entityFqdn": "wix.billing.v1.tax_group",
"slug": "updated",
"entityId": "ff1626eb-9e1e-4335-897a-d31a6d6a60da",
"updatedEvent": {
"currentEntity": {
"id": "ff1626eb-9e1e-4335-897a-d31a6d6a60da",
"name": "Test tax group",
"revision": "2",
"createdDate": "2024-02-05T08:52:26.071Z",
"updatedDate": "2024-02-05T08:52:58.910Z"
}
},
"eventTime": "2024-02-05T08:52:59.078929181Z",
"triggeredByAnonymizeRequest": false,
"entityEventSequence": "2"
}
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.
Unique event ID. Allows clients to ignore duplicate webhooks.
Fully qualified domain name of the entity associated with the event. Expected wix.billing.v1.tax_group
.
Event name. Expected deleted
.
ID of the entity associated with the event.
Event timestamp.
Whether the event was triggered as a result of a privacy regulation application (for example, GDPR).
If present, indicates the action that triggered the event.
Event information.
The data payload will include the following as an encoded JWT:
{
"data": {
"eventType": "wix.billing.v1.tax_group_deleted",
"instanceId": "<app-instance-id>",
"data": "<stringified-JSON>",
// The identity field is sent as a stringified JSON
"identity": {
"identityType": "<identityType>", // ANONYMOUS_VISITOR, MEMBER, WIX_USER, APP
"anonymousVisitorId": "<anonymousVisitorId>", // in case of ANONYMOUS_VISITOR
"memberId": "<memberId>", // in case of MEMBER
"wixUserId": "<wixUserId>", // in case of WIX_USER
"appId": "<appId>" // in case of APP
}
}
}
{
"id": "d6ac8c95-988c-4355-9df9-4cc6137b8348",
"entityFqdn": "wix.billing.v1.tax_group",
"slug": "deleted",
"entityId": "22b42643-3a47-47f8-90b7-9e8f64992cb7",
"deletedEvent": {
"movedToTrash": true
},
"eventTime": "2024-02-05T09:44:21.150721314Z",
"triggeredByAnonymizeRequest": false,
"entityEventSequence": "2"
}