About the Tax Calculation API
The Tax Calculation API allows you to retrieve the available tax calculators for a site and to calculate tax. Use the Tax Calculations API together with the Tax Groups API and the Tax Regions API to customize the application of tax for your business.
Before you begin
It's important to note the following before starting to code:
- Tax is calculated based on the tax region and a tax region requires an
appIdfor an available tax calculator. Use List Tax Calculators to retrieve a list of available tax calculators for a site, then create and manage your tax regions before calculating tax.
Use case
Terminology
- Tax calculator: An app that is used under the hood to calculate tax for a Wix site. The app calculates tax based on the tax group of the product and the tax region of the sale. A site assigns each tax region to the Wix manual tax calculator or an external calculator app to properly calculate tax.
- Wix manual tax calculator: The default tax calculator installed with a Wix site. The tax rates to apply for this calculator can be manually adjusted in the Tax Settings in the Wix dashboard.
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. You aren't limited to this exact flow, but it can be a helpful jumping off point as you plan your app's implementation.
Calculate multi-state tax for the United States
A business that operates in multiple U.S. states needs to charge and collect tax at different rates for each state. Your app can calculate the correct tax to apply.
To calculate tax for different states:
-
Use
listTaxCalculatorsto check which tax calculators the site has available to use for tax calculations. -
Use Create Tax Region and Create Tax Group to create any necessary regions or groups. Tax is calculated based on the tax region and tax group assigned to a product.
-
Instruct the site owner to update tax rates using the Tax Settings in the Wix dashboard, or add your own custom logic with the Tax Calculation Integration SPI.
-
When a cart or checkout is updated, Wix calls Calculate Tax and your tax settings will apply.
This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Calculates tax for the provided line items.
Tax is calculated for each line item based on the tax region
that corresponds to the address provided in lineItems.addressIndex and the tax group in taxGroupId. If no tax region is found for
the line item's address then no tax will be calculated for this line item. If no tax group with that taxGroupId is found then the
default tax group is used to calculate tax.
The tax is calculated by a tax calculator app installed on the site. Use List Tax Calculators to see which tax calculators are available. To provide your own tax calculations, use the Tax Calculation Integration SPI.
The breakdown of calculated tax returned, includes:
taxSummary: The overall total tax calculated.taxSummary.aggregatedTaxBreakdown: The total tax calculated for each jurisdiction.lineItemTaxDetails.taxSummary: The total tax calculated for each line item.lineItemTaxDetails.taxBreakdown: The tax calculated for each line item in each jurisdiction.
Permission Scopes
For app development, you must have one of the following permission scopes: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 installed tax calculators.
Wix uses these calculators to calculate tax.