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" } }
Event TriggersThis method triggers the following events:
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" } }
Did this help?

DELETE

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

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
DELETE
https://www.wixapis.com/billing/v1/tax-groups/{taxGroupId}

Path Params
taxGroupIdstringRequired

ID of the tax group to delete.

Response Object
Returns an empty object.
Delete TaxGroup

Deletes a TaxGroup by its ID

Request
cURL
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' \
Response
JSON
{}
Event TriggersThis method triggers the following events:
Did this help?

PATCH

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

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
PATCH
https://www.wixapis.com/billing/v1/tax-groups/{taxGroup.id}

Path Params
taxGroup.idstringRequired

Tax group ID.

Body Params
taxGroupTaxGroupRequired

Tax group info to update.

Response Object
taxGroupTaxGroup

Updated tax group.

Get TaxGroup

Get a TaxGroup by id

Request
cURL
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" ] } }'
Response
JSON
{ "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" } }
Errors
400Invalid Argument

There is 1 error with this status code:

See the entire list and learn more about Wix errors.

Event TriggersThis method triggers the following events:
Did this help?

POST

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

Permissions
Manage eCommerce - all 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/query

Body Params
queryQueryRequired

Query options.

Response Object
taxGroupsArray <TaxGroup>

Retrieved default tax groups.


pagingMetadataPagingMetadata

Paging metadata.

Query TaxGroup

Query tax groups

Request
cURL
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"}]}}'
Response
JSON
{ "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 } }
Did this help?

GET

List 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 Service Plugin.

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/default-tax-groups

Request
This endpoint does not take any parameters.
Response Object
taxGroupsArray <TaxGroup>

Retrieved default tax groups.

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

Request
cURL
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' \
Response
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 } ] }
Did this help?

POST

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

Permissions
Manage eCommerce - all 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/list-default-tax-groups-by-app-ids

Body Params
appIdsArray <string>RequiredminItems 1maxItems 300minLength 1

App IDs to retrieve default tax groups for.

Response Object
resultsArray <ListDefaultTaxGroupsByAppIdsResult>minItems 1maxItems 300

Retrieved default tax groups.


bulkActionMetadataBulkActionMetadata

Bulk action metadata.

List default tax groups by app ids

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.

Request
cURL
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" ] }'
Response
JSON
{ "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 } }
Did this help?

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.

Permissions
Manage eCommerce - all permissions
Manage Stores - all permissions
Manage Orders
Manage Restaurants - all permissions
Learn more about app permissions.
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.


createdEventCreatedEvent

Event information.

Event Body

The data payload will include the following as an encoded JWT:

JSON
{ "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 } } }

TaxGroupCreated
JSON
{ "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" }
Did this help?

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.

Permissions
Manage eCommerce - all permissions
Manage Stores - all permissions
Manage Orders
Manage Restaurants - all permissions
Learn more about app permissions.
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.


updatedEventUpdatedEvent

Event information.

Event Body

The data payload will include the following as an encoded JWT:

JSON
{ "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 } } }

TaxGroupUpdated
JSON
{ "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" }
Did this help?

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.

Permissions
Manage eCommerce - all permissions
Manage Stores - all permissions
Manage Orders
Manage Restaurants - all permissions
Learn more about app permissions.
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.

Event Body

The data payload will include the following as an encoded JWT:

JSON
{ "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 } } }

TaxGroupDeleted
JSON
{ "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" }
Did this help?