Go Headless

Build Apps

Client

API Preview

Ricos

Develop Websites

REST

Velo

GraphQL (Alpha)

payload

CalculateTaxEnvelope

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.

calculateTax

CalculateTaxResponse

# About the Tax Calculation Service Plugin

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](https://dev.wix.com/docs/sdk/backend-modules/billing/tax-groups/introduction) and the [Tax Regions API](https://dev.wix.com/docs/sdk/backend-modules/billing/tax-regions/introduction) to customize your tax calculations.

The integration is done via an app created in the [app dashboard](https://dev.wix.com/apps) with the Tax Calculation service plugin.

Learn more about [implementing an service plugin with Wix](https://dev.wix.com/docs/build-apps/develop-your-app/extensions/backend-extensions/service-plugins/about-service-plugin-extensions).

## Use case
+ [Calculate tax for the United Kingdom](https://dev.wix.com/docs/sdk/backend-modules/billing/service-plugins/tax-calculation-provider/sample-flows)

## Terminology
- **Tax Region:** A location, defined by `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](https://dev.wix.com/docs/sdk/backend-modules/billing/tax-regions/introduction).
- **Tax Group:** A category of products that share the same tax treatment. Tax is calculated based on the tax group and the tax region associated with a line item. See the [Tax Groups API](https://dev.wix.com/docs/sdk/backend-modules/billing/tax-groups/introduction).
- **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. By integrating with the Tax Calculation service plugin, your app becomes a tax calculator.

# Sample Use Cases and Flows

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.

## Calculate tax for the United Kingdom

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.
1. [Configure the service plugin](https://dev.wix.com/docs/sdk/backend-modules/billing/service-plugins/tax-calculation-provider/extension-config) and give it a `calculatorDisplayName`, such as `"UK Tax App"`.

1. Use [Tax Regions API](https://dev.wix.com/docs/sdk/backend-modules/billing/tax-regions/introduction) to create or update tax regions for the UK with your app ID in the `appId` field.

1. Add logic to your app so that when Wix calls it with [Calculate Tax](https://dev.wix.com/docs/sdk/backend-modules/billing/service-plugins/tax-calculation-provider/calculate-tax) your app returns a tax calculation based on different, relevant tax regions in [ISO-3166 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-2) format. 

billing_tax-calculation-provider

To configure and customize your service plugin, you need to provide important details in the `plugin.json` configuration file.

Extension Config

TaxCalculationConfig

Address

Main address line, usually street and number as free text.

addressLine1

string

Free text providing more detailed address information, such as apartment, suite, or floor.

addressLine2

city

2-letter country code in [ISO-3166 alpha-1](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements) format.

country

postalCode

Subdivision (such as state, prefecture, or province) in [ISO-3166 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-2) format.

subdivision

AddressIndex

Multiple addresses to use for a sale. For example, some tax calculations may require both the address where an item is shipped from,
as well as the address the item is shipped to.

multipleAddresses

Single address to use for a sale location when only one address is required for tax calculations. The index is zero-based.

singleAddress

AlternativeUri

Custom URI that Wix uses to call your server for this method. The path-suffix documented in the method will not be appended to this URI.
Must be a secured endpoint beginning with `https://`. For example, `https://www.my-shipping-provider.com/my-shipping-rates`.

absoluteUri

Name of the method to create a custom URI for.

For `methodName`, use the name of the method in PascalCase.
For example, for Get Shipping Rates use `GetShippingRates`.

methodName

metadata

Context

request

CalculateTaxRequest

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

addresses

3-letter currency code in [ISO-4217 alphabetic](https://en.wikipedia.org/wiki/ISO_4217#Active_codes) format.

currency

lineItems

3-letter currency code in [ISO-4217 alphabetic](https://en.wikipedia.org/wiki/ISO_4217#Active_codes) format.
If this code doesn't match the `currency` passed in the request, then the response is invalid.

Details of each tax applied to each line item.

lineItemTaxDetails

taxSummary

TaxSummary

[ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) 3-letter currency code.

An object that describes the identity that triggered this request.

identity

IdentificationData

instanceId

A string representing a language and region in the format of `"xx-XX"`. First 2 letters represent the language code according to ISO 639-1. This is followed by a dash "-", and then a by 2 capital letters representing the region according to ISO 3166-2. For example, `"en-US"`.

languages

A unique identifier of the request. You may print this ID to your logs to help with future debugging and easier correlation with Wix's logs.

requestId

ID of a site visitor that has not logged in to the site.

anonymousVisitorId

appId

ID of a site visitor that has logged in to the site.

memberId

ID of a Wix user (site owner, contributor, etc.).

wixUserId

identityType

IdentityType

JurisdictionType

LineItem

Index of the address from `addresses` to use to calculate tax for this specific line item. The index is zero-based.

addressIndex

Stock keeping unit for this line item. Learn more about [SKUs](https://www.wix.com/encyclopedia/definition/stock-keeping-unit-sku).

itemCode

itemName

price

quantity

number

Tax group ID for this line item. If not provided, the default tax group applies.

taxGroupId

taxIncludedInPrice

boolean

taxRegionId

LineItemTaxDetails

Array of each tax applied, grouped by `jurisdiction`, `jurisdictionType`, `taxName`, `rate`, and `taxType`.

taxBreakdown

Summary of this line item's total price and tax.

LineItemTaxSummary

Total price for this line item.
To determine the price for each individual unit of this line item, divide by `quantity`.

fullPrice

The total amount of tax calculated for this line item.

taxAmount

taxableAmount

MultipleAddresses

destination

origin

SpiBaseUri

Alternate, custom URIs to replace the default URIs for specific service plugin methods.

alternativeUris

Base URI where the methods are called. Wix appends the path to the `baseUri`.
For example, to call the Get Shipping Rates method at `https://my-shipping-provider.com/v1/getRates`, the base URI you provide here is `https://my-shipping-provider.com/`.

baseUri

TaxBreakdown

Jurisdiction that taxes were calculated for.

jurisdiction

Type of jurisdiction that taxes were calculated for. For example, `"State"`, `"County"`, `"City"`, `"Special"`, etc.

jurisdictionType

nonTaxableAmount

Tax rate used for this jurisdiction, as a decimal. For example, 10% tax is `"0.1000"` and 200% tax is `"2.0000"`.

rate

Amount of this tax calculated for this jurisdiction.

Name of the tax that was calculated. For example, `"NY State Sales Tax"`, `"Quebec GST"`, etc.

taxName

Type of tax that was calculated. For example, `"Sales Tax"`, `"Income Tax"`, `"Value Added Tax"`, etc.

taxType

calculatorDisplayName

*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/"`.

deploymentUri

List of countries, in [ISO-3166 alpha-1](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements) format, that the calculator does not support.

unsupportedCountries

totalAmount

Total amount of tax calculated for all line items.
Note that due to rounding, `totalTax` may not equal the sum of `lineItemTaxDetails.taxSummary.taxAmount`.

totalTax

Total amount of `totalTax` that is included in price. Applies to line items with `taxIncludedInPrice` set to `true`.

Extension Config

calculateTax( )