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:

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

  1. Use List Tax Calculators to check which tax calculators the site has available to use for tax calculations.

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

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

  4. When a cart or checkout is updated, Wix calls Calculate Tax and your tax settings will apply.

Did this help?

POST

Calculate Tax


Developer Preview

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.
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/calculate-tax

Body Params
externalIdstringformat GUID

Optional ID of the entity that tax is being calculated for. For example, a cart ID.


currencystringformat CURRENCY

3-letter currency code in ISO-4217 alphabetic format.


addressesArray <Address>RequiredminItems 1maxItems 2

Array of addresses. Each line item can individually reference the address to apply with lineItems.addressIndex.


lineItemsArray <LineItem>RequiredminItems 1maxItems 300

Line items to calculate tax for.

Response Object
externalIdstringformat GUID

Optional ID of the entity that tax is being calculated for. For example, a cart ID.


currencystringformat CURRENCY

3-letter currency code in ISO-4217 alphabetic format.


addressesArray <Address>minItems 1maxItems 2

Array of addresses. Each line item can individually reference the address to apply with lineItems.addressIndex.


taxSummaryTaxSummary

Summary of the tax calculated.


lineItemTaxDetailsArray <LineItemTaxDetails>minItems 1maxItems 300

Details of each tax applied to each line item.


errorsArray <ApplicationError>minItems 0maxItems 100

Errors that occurred during the tax calculation.

Calculate Tax

Trigger a tax calculation for a given set of line items and their addresses.

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

There is 1 error with this status code:

428Failed Precondition

There are 3 errors with this status code:

See the entire list and learn more about Wix errors.

Did this help?

GET

List Tax Calculators


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 installed tax calculators.

Wix uses these calculators 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
GET
https://www.wixapis.com/billing/v1/list-tax-calculators

Request
This endpoint does not take any parameters.
Response Object
taxCalculatorDetailsArray <TaxCalculatorDetails>maxItems 10

Retrieved tax calculators.

List Tax Calculators

List all tax calculators installed and their details

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