> Portal Navigation: > > - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version. > - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages). > - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`). > - Top-level index of all portals: https://dev.wix.com/docs/llms.txt > - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt # CalculateTax # Package: tax # Namespace: TaxCalculationProvider # Method link: https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/extensions/tax/tax-calculation-integration-service-plugin/calculate-tax.md ## Introduction 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. --- ## REST API ### Schema ``` Method: calculateTax Description: 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. URL: null Method: POST Method parameters: param name: addresses | type: array | description: Array of addresses. Each line item can individually reference the address to apply with `lineItems.addressIndex`. - name: country | type: string | description: 2-letter country code in [ISO-3166 alpha-1](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements) format. - name: subdivision | type: string | description: Subdivision (such as state, prefecture, or province) in [ISO-3166 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-2) format. - name: city | type: string | description: City name. - name: postalCode | type: string | description: Postal or zip code. - name: addressLine | type: string | description: Main address line, usually street and number as free text. - name: addressLine2 | type: string | description: Free text providing more detailed address information, such as apartment, suite, or floor. param name: currency | type: currency | description: 3-letter currency code in [ISO-4217 alphabetic](https://en.wikipedia.org/wiki/ISO_4217#Active_codes) format. param name: lineItems | type: array | description: Line items to calculate tax for. - name: id | type: string | description: Line item GUID. - name: itemName | type: string | description: Line item name to display. - name: quantity | type: integer | description: Line item quantity. - name: price | type: string | description: Line item price. - name: itemCode | type: string | description: Stock keeping unit for this line item. Learn more about [SKUs](https://www.wix.com/encyclopedia/definition/stock-keeping-unit-sku). - name: taxGroupId | type: string | description: Tax group GUID for this line item. If not provided, the default tax group applies. - name: taxIncludedInPrice | type: boolean | description: Whether tax is included in the price. - name: addressIndex | type: AddressIndex | description: Index of the address from `addresses` to use to calculate tax for this specific line item. The index is zero-based. - ONE-OF: - name: singleAddress | type: integer | description: Single address to use for a sale location when only one address is required for tax calculations. The index is zero-based. - name: multipleAddresses | type: MultipleAddresses | description: 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. - name: origin | type: integer | description: Index of the origin address. - name: destination | type: integer | description: Index of the destination address. - name: taxRegionId | type: string | description: Tax region GUID for this line item. Return type: CalculateTaxResponse - name: currency | type: string | description: 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. - name: taxSummary | type: TaxSummary | description: Summary of the tax calculated. - name: totalAmount | type: string | description: Total price for all line items. - name: totalTax | type: string | description: Total amount of tax calculated for all line items. Note that due to rounding, `totalTax` may not equal the sum of `lineItemTaxDetails.taxSummary.taxAmount`. - name: totalTaxableAmount | type: string | description: Total taxable amount for all line items. - name: totalTaxIncludedInPrice | type: string | description: Total amount of `totalTax` that is included in price. Applies to line items with `taxIncludedInPrice` set to `true`. - name: lineItemTaxDetails | type: array | description: Details of each tax applied to each line item. - name: id | type: string | description: Line item GUID. - name: itemName | type: string | description: Line item name to display. - name: quantity | type: integer | description: Line item quantity. - name: taxBreakdown | type: array | description: Array of each tax applied, grouped by `jurisdiction`, `jurisdictionType`, `taxName`, `rate`, and `taxType`. - name: jurisdiction | type: string | description: Jurisdiction that taxes were calculated for. - name: nonTaxableAmount | type: string | description: Non-taxable amount of the price. - name: rate | type: string | description: Tax rate used for this jurisdiction, as a decimal. For example, 10% tax is `"0.1000"` and 200% tax is `"2.0000"`. - name: taxAmount | type: string | description: Amount of this tax calculated for this jurisdiction. - name: taxableAmount | type: string | description: Taxable amount of the price. - name: taxType | type: string | description: Type of tax that was calculated. For example, `"Sales Tax"`, `"Income Tax"`, `"Value Added Tax"`, etc. - name: taxName | type: string | description: Name of the tax that was calculated. For example, `"NY State Sales Tax"`, `"Quebec GST"`, etc. - name: jurisdictionType | type: JurisdictionType | description: Type of jurisdiction that taxes were calculated for. For example, `"State"`, `"County"`, `"City"`, `"Special"`, etc. - enum: UNDEFINED, COUNTRY, STATE, COUNTY, CITY, SPECIAL - name: taxSummary | type: LineItemTaxSummary | description: Summary of this line item's total price and tax. - name: fullPrice | type: string | description: Total price for this line item. To determine the price for each individual unit of this line item, divide by `quantity`. - name: taxAmount | type: string | description: The total amount of tax calculated for this line item. - name: taxableAmount | type: string | description: Total taxable amount for this line item. ``` ### Examples ### Calculate Tax Trigger a tax calculation for a given set of line items and their addresses. ```curl 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: ' \ --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" }' ``` --- ## JavaScript SDK ### Schema ``` Method: wixClientAdmin.tax.TaxCalculationProvider.calculateTax(request, metadata) Description: 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. Method parameters: param name: metadata | type: Context | description: this message is not directly used by any service, it exists to describe the expected parameters that SHOULD be provided to invoked Velo methods as part of open-platform. e.g. SPIs, event-handlers, etc.. NOTE: this context object MUST be provided as the last argument in each Velo method signature. Example: ```typescript export function wixStores_onOrderCanceled({ event, metadata }: OrderCanceledEvent) { ... } ``` - name: requestId | type: string | description: A unique identifier of the request. You may print this GUID to your logs to help with future debugging and easier correlation with Wix's logs. - name: currency | type: string | description: [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) 3-letter currency code. - name: identity | type: IdentificationData | description: An object that describes the identity that triggered this request. - ONE-OF: - name: anonymousVisitorId | type: string | description: GUID of a site visitor that has not logged in to the site. - name: memberId | type: string | description: GUID of a site visitor that has logged in to the site. - name: wixUserId | type: string | description: GUID of a Wix user (site owner, contributor, etc.). - name: appId | type: string | description: GUID of an app. - name: languages | type: array | description: 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"`. - name: instanceId | type: string | description: The service provider app's instance GUID. param name: request | type: CalculateTaxRequest | description: Items and information to calculate tax for. - name: currency | type: string | description: 3-letter currency code in [ISO-4217 alphabetic](https://en.wikipedia.org/wiki/ISO_4217#Active_codes) format. - name: addresses | type: array
| description: Array of addresses. Each line item can individually reference the address to apply with `lineItems.addressIndex`. - name: city | type: string | description: none - name: subdivision | type: string | description: none - name: country | type: string | description: none - name: postalCode | type: string | description: none - name: addressLine2 | type: string | description: none - name: lineItems | type: array | description: Line items to calculate tax for. - name: _id | type: string | description: Line item GUID. - name: itemName | type: string | description: Line item name to display. - name: quantity | type: integer | description: Line item quantity. - name: price | type: string | description: Line item price. - name: itemCode | type: string | description: Stock keeping unit for this line item. Learn more about [SKUs](https://www.wix.com/encyclopedia/definition/stock-keeping-unit-sku). - name: taxGroupId | type: string | description: Tax group GUID for this line item. If not provided, the default tax group applies. - name: taxIncludedInPrice | type: boolean | description: Whether tax is included in the price. - name: addressIndex | type: AddressIndex | description: Index of the address from `addresses` to use to calculate tax for this specific line item. The index is zero-based. - ONE-OF: - name: singleAddress | type: integer | description: Single address to use for a sale location when only one address is required for tax calculations. The index is zero-based. - name: multipleAddresses | type: MultipleAddresses | description: 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. - name: origin | type: integer | description: Index of the origin address. - name: destination | type: integer | description: Index of the destination address. - name: taxRegionId | type: string | description: Tax region GUID for this line item. Return type: PROMISE - name: currency | type: string | description: 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. - name: taxSummary | type: TaxSummary | description: Summary of the tax calculated. - name: totalAmount | type: string | description: Total price for all line items. - name: totalTax | type: string | description: Total amount of tax calculated for all line items. Note that due to rounding, `totalTax` may not equal the sum of `lineItemTaxDetails.taxSummary.taxAmount`. - name: totalTaxableAmount | type: string | description: Total taxable amount for all line items. - name: totalTaxIncludedInPrice | type: string | description: Total amount of `totalTax` that is included in price. Applies to line items with `taxIncludedInPrice` set to `true`. - name: lineItemTaxDetails | type: array | description: Details of each tax applied to each line item. - name: _id | type: string | description: Line item GUID. - name: itemName | type: string | description: Line item name to display. - name: quantity | type: integer | description: Line item quantity. - name: taxBreakdown | type: array | description: Array of each tax applied, grouped by `jurisdiction`, `jurisdictionType`, `taxName`, `rate`, and `taxType`. - name: jurisdiction | type: string | description: Jurisdiction that taxes were calculated for. - name: nonTaxableAmount | type: string | description: Non-taxable amount of the price. - name: rate | type: string | description: Tax rate used for this jurisdiction, as a decimal. For example, 10% tax is `"0.1000"` and 200% tax is `"2.0000"`. - name: taxAmount | type: string | description: Amount of this tax calculated for this jurisdiction. - name: taxableAmount | type: string | description: Taxable amount of the price. - name: taxType | type: string | description: Type of tax that was calculated. For example, `"Sales Tax"`, `"Income Tax"`, `"Value Added Tax"`, etc. - name: taxName | type: string | description: Name of the tax that was calculated. For example, `"NY State Sales Tax"`, `"Quebec GST"`, etc. - name: jurisdictionType | type: JurisdictionType | description: Type of jurisdiction that taxes were calculated for. For example, `"State"`, `"County"`, `"City"`, `"Special"`, etc. - enum: UNDEFINED, COUNTRY, STATE, COUNTY, CITY, SPECIAL - name: taxSummary | type: LineItemTaxSummary | description: Summary of this line item's total price and tax. - name: fullPrice | type: string | description: Total price for this line item. To determine the price for each individual unit of this line item, divide by `quantity`. - name: taxAmount | type: string | description: The total amount of tax calculated for this line item. - name: taxableAmount | type: string | description: Total taxable amount for this line item. ``` ### Examples ### calculateTax ```javascript import { taxCalculationProvider } from '@wix/billing/service-plugins'; async function calculateTax(request,metadata) { const response = await taxCalculationProvider.calculateTax(request,metadata); }; ``` ### calculateTax (with elevated permissions) ```javascript import { taxCalculationProvider } from '@wix/billing/service-plugins'; import { auth } from '@wix/essentials'; async function myCalculateTaxMethod(request,metadata) { const elevatedCalculateTax = auth.elevate(taxCalculationProvider.calculateTax); const response = await elevatedCalculateTax(request,metadata); } ``` ### calculateTax (self-hosted) Self-hosted SDK calls require you to [create a client](https://dev.wix.com/docs/sdk/articles/work-with-the-sdk/about-the-wix-client.md). ```javascript import { createClient } from '@wix/sdk'; import { taxCalculationProvider } from '@wix/billing/service-plugins'; // Import the auth strategy for the relevant access type // Import the relevant host module if needed const myWixClient = createClient ({ modules: { taxCalculationProvider }, // Include the auth strategy and host as relevant }); async function calculateTax(request,metadata) { const response = await myWixClient.taxCalculationProvider.calculateTax(request,metadata); }; ``` ---