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.
It's important to note the following before starting to code:
appId
for 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.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.
A business that operates in multiple U.S. states may need 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 List Tax Calculators to 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 Service Plugin.
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 Service Plugin.
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.Optional ID of the entity that tax is being calculated for. For example, a cart ID.
3-letter currency code in ISO-4217 alphabetic format.
Array of addresses. Each line item can individually reference the address to apply with lineItems.addressIndex
.
Line items to calculate tax for.
Optional ID of the entity that tax is being calculated for. For example, a cart ID.
3-letter currency code in ISO-4217 alphabetic format.
Array of addresses. Each line item can individually reference the address to apply with lineItems.addressIndex
.
Summary of the tax calculated.
Details of each tax applied to each line item.
Errors that occurred during the tax calculation.
Trigger a tax calculation for a given set of line items and their addresses.
curl --location 'https://www.wixapis.com/billing/v1/calculate-tax' \
--header 'accept: application/json, text/plain, */*' \
--header 'accept-language: en-US,en;q=0.9' \
--header 'authorization: <AUTH>' \
--header 'content-type: application/json' \
--data '{
"line_items": [
{
"id": "item123",
"item_name": "some",
"price": "123",
"tax_group_id": "56ce0f07-adda-4419-9d16-1af86b2ed284",
"app_id": "215238eb-22a5-4c36-9e7b-e7c08025e04e",
"tax_included": false,
"address_index": {
"single_address": 0
},
"quantity": 4
}
],
"addresses": [
{
"country": "US",
"subdivision": "TX",
"postal_code": "76248",
"address_line": "296 Valley View Street Keller, TX 76248"
}
],
"currency": "USD",
"external_id": "e519e0e5-5336-4fee-86d0-b7fbf750dda0"
}'
{
"externalId": "e519e0e5-5336-4fee-86d0-b7fbf750dda0",
"currency": "USD",
"addresses": [
{
"country": "US",
"subdivision": "TX",
"postalCode": "76248",
"addressLine": "296 Valley View Street Keller, TX 76248"
}
],
"taxSummary": {
"totalAmount": "123.00",
"totalTax": "10.15",
"totalTaxableAmount": "123.00",
"totalTaxIncludedInPrice": "0.00",
"aggregatedTaxBreakdown": [
{
"taxName": "TX STATE TAX",
"taxType": "Sales",
"jurisdiction": "TEXAS",
"jurisdictionType": "STATE",
"rate": "0.0625",
"aggregatedTaxAmount": "7.69"
},
{
"taxName": "TX CITY TAX",
"taxType": "Sales",
"jurisdiction": "KELLER",
"jurisdictionType": "CITY",
"rate": "0.0175",
"aggregatedTaxAmount": "2.15"
},
{
"taxName": "TX SPECIAL TAX",
"taxType": "Sales",
"jurisdiction": "KELLER CRIME CONTROL",
"jurisdictionType": "SPECIAL",
"rate": "0.0025",
"aggregatedTaxAmount": "0.31"
}
]
},
"lineItemTaxDetails": [
{
"id": "item123",
"itemName": "some",
"quantity": 4,
"taxBreakdown": [
{
"jurisdiction": "TEXAS",
"nonTaxableAmount": "0.00",
"rate": "0.0625",
"taxAmount": "7.69",
"taxableAmount": "123.00",
"taxType": "Sales",
"taxName": "TX STATE TAX",
"jurisdictionType": "STATE"
},
{
"jurisdiction": "KELLER",
"nonTaxableAmount": "0.00",
"rate": "0.0175",
"taxAmount": "2.15",
"taxableAmount": "123.00",
"taxType": "Sales",
"taxName": "TX CITY TAX",
"jurisdictionType": "CITY"
},
{
"jurisdiction": "KELLER CRIME CONTROL",
"nonTaxableAmount": "0.00",
"rate": "0.0025",
"taxAmount": "0.31",
"taxableAmount": "123.00",
"taxType": "Sales",
"taxName": "TX SPECIAL TAX",
"jurisdictionType": "SPECIAL"
}
],
"taxSummary": {
"fullPrice": "123.00",
"taxAmount": "10.15",
"taxableAmount": "123.00",
"appId": "7516f85b-0868-4c23-9fcb-cea7784243df"
},
"addressIndex": {
"singleAddress": 0
}
}
],
"errors": []
}
There is 1 error with this status code:
There are 3 errors 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 installed tax calculators.
Wix uses these calculators to calculate tax.
You can only call this method when authenticated as a Wix app or Wix user identity.
Retrieved tax calculators.
List all tax calculators installed and their details
curl --location 'https://www.wixapis.com/billing/v1/list-tax-calculators' \
--header 'accept: application/json, text/plain, */*' \
--header 'accept-language: en-US,en;q=0.9' \
--header 'authorization: <AUTH>' \
--header 'content-type: application/json' \
{
"taxCalculatorDetails": [
{
"appId": "7516f85b-0868-4c23-9fcb-cea7784243df",
"displayName": "Avalara Tax Calculator",
"unsupportedCountries": [
"BR",
"IN",
"AQ",
"AS",
"AX",
"BV",
"EH",
"FM",
"GU",
"HM",
"IM",
"MH",
"MP",
"PR",
"PW",
"UM",
"VI"
]
},
{
"appId": "57d13128-4a4c-494b-80b3-a6fb2e28018d",
"displayName": "Wix Manual Tax Calculator",
"unsupportedCountries": []
}
]
}