The Tax Calculation service plugin (formerly SPI) allows you to integrate a custom tax calculation service with Wix. Use the Tax Calculation service plugin together with the Tax Groups API and the Tax Regions API to customize your tax calculations.
The integration is done via an app created in the app dashboard with the Tax Calculation service plugin.
Learn more about implementing an service plugin with Wix.
country
and subdivision
with a specific tax treatment. Tax is calculated based on the tax region and the tax group associated with a line item. See the Tax Regions API.With the Tax Calculation service plugin integrated into your app, Wix will call your app with Calculate Tax whenever tax needs to be recalculated on a site. For example, when line items are updated in a cart or checkout. Follow these steps to add the service plugin and enable Wix to communicate with your app.
Go to the Extensions tab in the Wix Dev Center.
Click + Create Extension in the top right.
Find Tax Calculation Provider and click + Create.
Use the JSON editor to create the extension's configuration file. Configure the parameters by referencing the table below or the Documentation section to the right of the editor. For each parameter, add the parameter name and value in the JSON editor.
Name | Type | Description |
---|---|---|
deploymentUri | string | Required. Base URI where the endpoints are called. Wix appends the endpoint path to the base URI. For example, to call the Calculate Tax endpoint at https://my-tax-calc.com/v1/calculateTax, the base URI you provide here is https://my-tax-calc.com/. |
calculatorDisplayName | string | Display name of the tax calculator. |
unsupportedCountries | array | List of countries, in ISO-3166 alpha-1 format, that the calculator does not support. |
componentName | string | A unique name for this component. This is an internal name that will only appear in the Dev Center. |
Click Test Your App.
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 these exact flows, but it can be a helpful jumping off point as you plan your app's implementation.
A business operating in the United Kingdom needs to charge and collect tax at different rates throughout the country. Your app can provide the correct tax to charge for their sales.
Follow these steps to create an app that can calculate tax for the United Kingdom.
Configure the service plugin and give it a calculatorDisplayName
, such as "UK Tax App"
.
Use Tax Regions API to create or update tax regions for the UK with your app ID in the appId
field.
Add logic to your app so that when Wix calls it with Calculate Tax your app returns a tax calculation based on different, relevant tax regions in ISO-3166 alpha-2 format.
[Optional] You may also want to offer additional tax rates based on different categories of products. Use the Tax Groups service plugin to configure such tax groups.
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
in lineItems.taxRegionId
and the tax group in lineItems.taxGroupId
.
The breakdown of calculated tax returned, includes:
taxSummary
: The overall total tax calculated.lineItemTaxDetails.taxBreakdown
: The tax calculated for each line item in each jurisdiction.lineItemTaxDetails.taxSummary
: The total tax calculated for each line item.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.
3-letter currency code in ISO-4217 alphabetic format.
If this code doesn't match the currency
passed in the request, then the response is invalid.
Summary of the tax calculated.
Details of each tax applied to each line item.
Trigger a tax calculation for a given set of line items and their addresses.
curl -X POST 'https://provider.example.com/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 '{
"lineItems": [
{
"id": "item123",
"item_name": "some",
"price": "123",
"tax_group_id": "56ce0f07-adda-4419-9d16-1af86b2ed284",
"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"
}'
{
"currency": "USD",
"tax_summary": {
"total_amount": "123.00",
"total_tax": "10.15",
"total_taxable_amount": "123.00",
"total_tax_included_in_price": "0.00"
},
"line_item_tax_details": [
{
"id": "item123",
"item_name": "some",
"quantity": 4,
"tax_breakdown": [
{
"jurisdiction": "TEXAS",
"non_taxable_amount": "0.00",
"rate": "0.0625",
"tax_amount": "7.69",
"taxable_amount": "123.00",
"tax_type": "Sales",
"tax_name": "TX STATE TAX",
"jurisdiction_type": "STATE"
},
{
"jurisdiction": "KELLER",
"non_taxable_amount": "0.00",
"rate": "0.0175",
"tax_amount": "2.15",
"taxable_amount": "123.00",
"tax_type": "Sales",
"tax_name": "TX CITY TAX",
"jurisdiction_type": "CITY"
},
{
"jurisdiction": "KELLER CRIME CONTROL",
"non_taxable_amount": "0.00",
"rate": "0.0025",
"tax_amount": "0.31",
"taxable_amount": "123.00",
"tax_type": "Sales",
"tax_name": "TX SPECIAL TAX",
"jurisdiction_type": "SPECIAL"
}
],
"tax_summary": {
"full_price": "123.00",
"tax_amount": "10.15",
"taxable_amount": "123.00"
}
}
]
}