> 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: TaxCalculation # Method link: https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/extensions/tax/tax-calculation/calculate-tax.md ## Permission Scopes: Manage Orders: SCOPE.DC-STORES.MANAGE-ORDERS ## Introduction 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. The tax is calculated by a tax calculator app installed on the site. Call List Tax Calculators to see which tax calculators are available. To provide your own tax calculations, use the Tax Calculation 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. --- ## 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 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. The tax is calculated by a tax calculator app installed on the site. Call List Tax Calculators to see which tax calculators are available. To provide your own tax calculations, use the Tax Calculation 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. URL: https://www.wixapis.com/billing/v1/calculate-tax Method: POST # Note: If the parameter `a.b` is listed under required parameters, `b` is only required if `a` is also present. Required parameters: addresses, lineItems, lineItems.id, lineItems.price, lineItems.addressIndex Method parameters: param name: addresses | type: array | description: Array of addresses. Each line item can individually reference the address to apply with `lineItems.addressIndex`. | required: true - 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: externalId | type: externalId | description: Optional GUID of the entity that tax is being calculated for. For example, a cart GUID. param name: lineItems | type: array | description: Line items to calculate tax for. | required: true - name: id | type: string | description: Line item GUID. | required: true - 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. | required: true - 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: appId | type: string | description: GUID of the app providing the catalog for this line item. You can get your app's GUID from its page in the [app dashboard](https://dev.wix.com/dc3/my-apps/). For items from Wix catalogs, the following values always apply: + Wix Stores: `"215238eb-22a5-4c36-9e7b-e7c08025e04e"` + Wix Bookings: `"13d21c63-b5ec-5912-8397-c3a5ddb27a97"` + Wix Restaurants: `"9a5d83fd-8570-482e-81ab-cfa88942ee60"` - 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. | required: true - 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. Return type: CalculateTaxResponse - name: externalId | type: string | description: Optional GUID of the entity that tax is being calculated for. For example, a cart GUID. - 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: 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. - 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: aggregatedTaxBreakdown | type: array | description: Array of each tax applied, grouped by `"jurisdiction"`, `"jurisdictionType"`, `"taxType"`, `"taxName"` and `"rate"`. - name: taxName | type: string | description: Name of the tax that was calculated. - name: taxType | type: string | description: Type of tax that was calculated. - name: jurisdiction | type: string | description: Jurisdiction that taxes were calculated for. - name: jurisdictionType | type: JurisdictionType | description: Type of jurisdiction that taxes were calculated for. - enum: UNDEFINED, COUNTRY, STATE, COUNTY, CITY, SPECIAL - 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: aggregatedTaxAmount | type: string | description: Total amount of this tax for this jurisdiction. - 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`. - 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"`, `"Çounty"`, `"City"`, `"Special"`, etc. - 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: Total amount of tax calculated for this line item. - name: taxableAmount | type: string | description: Total taxable amount for this line item. - name: appId | type: string | description: GUID of the calculator app that calculated tax for this line item. - 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: taxIncludedInPrice | type: boolean | description: Whether tax is included in the price. - name: errors | type: array | description: Errors that occurred during the tax calculation. - name: code | type: string | description: Error code. - name: description | type: string | description: Description of the error. - name: data | type: object | description: Data related to the error. Possible Errors: HTTP Code: 400 | Status Code: INVALID_ARGUMENT | Application Code: INVALID_LINE_ITEM_ADDRESS_INDEX | Description: The `addressIndex` value in one or more line items doesn't reference a valid address in the `addresses` array. HTTP Code: 428 | Status Code: FAILED_PRECONDITION | Application Code: MISSING_SUBDIVISION_IN_ADDRESS | Description: The `subdivision` field is missing in one or more addresses. HTTP Code: 428 | Status Code: FAILED_PRECONDITION | Application Code: MISSING_COUNTRY_IN_ADDRESS | Description: The `country` field is missing in one or more addresses. HTTP Code: 428 | Status Code: FAILED_PRECONDITION | Application Code: MISSING_TAXABLE_ADDRESS | Description: No taxable address was provided for tax calculation. ``` ### Examples ### Calculate Tax Trigger a tax calculation for a given set of line items and their addresses. ```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: ' \ --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" }' ``` --- ## JavaScript SDK ### Schema ``` Method: wixClientAdmin.tax.TaxCalculation.calculateTax(options) Description: 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. The tax is calculated by a tax calculator app installed on the site. Call List Tax Calculators to see which tax calculators are available. To provide your own tax calculations, use the Tax Calculation 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. # Note: If the parameter `a.b` is listed under required parameters, `b` is only required if `a` is also present. Required parameters: options.addresses, options.lineItems, options.lineItems._id, options.lineItems.price, options.lineItems.addressIndex, options Method parameters: param name: options | type: CalculateTaxOptions none | required: true - name: externalId | type: string | description: Optional GUID of the entity that tax is being calculated for. For example, a cart GUID. - 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`. | required: true - 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. - name: lineItems | type: array | description: Line items to calculate tax for. | required: true - 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: appId | type: string | description: GUID of the app providing the catalog for this line item. You can get your app's GUID from its page in the [app dashboard](https://dev.wix.com/dc3/my-apps/). For items from Wix catalogs, the following values always apply: + Wix Stores: `"215238eb-22a5-4c36-9e7b-e7c08025e04e"` + Wix Bookings: `"13d21c63-b5ec-5912-8397-c3a5ddb27a97"` + Wix Restaurants: `"9a5d83fd-8570-482e-81ab-cfa88942ee60"` - 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. Return type: PROMISE - name: externalId | type: string | description: Optional GUID of the entity that tax is being calculated for. For example, a cart GUID. - 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: 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: aggregatedTaxBreakdown | type: array | description: Array of each tax applied, grouped by `"jurisdiction"`, `"jurisdictionType"`, `"taxType"`, `"taxName"` and `"rate"`. - name: taxName | type: string | description: Name of the tax that was calculated. - name: taxType | type: string | description: Type of tax that was calculated. - name: jurisdiction | type: string | description: Jurisdiction that taxes were calculated for. - name: jurisdictionType | type: JurisdictionType | description: Type of jurisdiction that taxes were calculated for. - enum: UNDEFINED, COUNTRY, STATE, COUNTY, CITY, SPECIAL - 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: aggregatedTaxAmount | type: string | description: Total amount of this tax for this jurisdiction. - 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`. - 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"`, `"Çounty"`, `"City"`, `"Special"`, etc. - 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: Total amount of tax calculated for this line item. - name: taxableAmount | type: string | description: Total taxable amount for this line item. - name: appId | type: string | description: GUID of the calculator app that calculated tax for this line item. - 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: taxIncludedInPrice | type: boolean | description: Whether tax is included in the price. - name: errors | type: array | description: Errors that occurred during the tax calculation. - name: code | type: string | description: Error code. - name: description | type: string | description: Description of the error. - name: data | type: object | description: Data related to the error. Possible Errors: HTTP Code: 400 | Status Code: INVALID_ARGUMENT | Application Code: INVALID_LINE_ITEM_ADDRESS_INDEX | Description: The `addressIndex` value in one or more line items doesn't reference a valid address in the `addresses` array. HTTP Code: 428 | Status Code: FAILED_PRECONDITION | Application Code: MISSING_SUBDIVISION_IN_ADDRESS | Description: The `subdivision` field is missing in one or more addresses. HTTP Code: 428 | Status Code: FAILED_PRECONDITION | Application Code: MISSING_COUNTRY_IN_ADDRESS | Description: The `country` field is missing in one or more addresses. HTTP Code: 428 | Status Code: FAILED_PRECONDITION | Application Code: MISSING_TAXABLE_ADDRESS | Description: No taxable address was provided for tax calculation. ``` ### Examples ### calculateTax ```javascript import { taxCalculation } from '@wix/ecom'; async function calculateTax(options) { const response = await taxCalculation.calculateTax(options); }; ``` ### calculateTax (with elevated permissions) ```javascript import { taxCalculation } from '@wix/ecom'; import { auth } from '@wix/essentials'; async function myCalculateTaxMethod(options) { const elevatedCalculateTax = auth.elevate(taxCalculation.calculateTax); const response = await elevatedCalculateTax(options); } ``` ### 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 { taxCalculation } from '@wix/ecom'; // Import the auth strategy for the relevant access type // Import the relevant host module if needed const myWixClient = createClient ({ modules: { taxCalculation }, // Include the auth strategy and host as relevant }); async function calculateTax(options) { const response = await myWixClient.taxCalculation.calculateTax(options); }; ``` ---