--- schema_version: "1" id: 91e6ae384bd0dcc0ab47a2379c1f1065ee7cef0d4dcc4a39c1a7d69f61053647 title: Tax Calculation SPI collection: developer version: current locale: en-us portal_url: https://docs.salesforce.com/developer/current/en-us/commerce-cloud/retail-cloud/reference/generated-api-specs/tax-calculation-spi.md canonical_url: https://developer.salesforce.com/docs/commerce/retail-cloud/references/tax-calculation-spi source_site: developer.salesforce.com content_type: documentation content_hash: 6898e54475969ec1b78a92bb135b6b2602d5ae1a8468c737f24ca3b364b86dd7 products: - Point of Sale for Developers - Salesforce APIs --- Tax Calculation SPI # Tax Calculation SPI [Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/tax-calculation-spi/tax-calculation-spi-oas-public.yaml) Merchant SPI to calculate taxes for a transaction according to the rules defined in the tax engine of the merchant's system. APIs include tax calculation, getting tax exemptions, and downloading tax rates for offline transactions. ### Configuration 1. **Store Management** > **Integration** > **Custom API Connectors** > **Create** * **API KEY:** TAX\_SERVICE with authentication details and URL Base. * All the APIs defined below will use this URL base; only the last keyword will change. 2. Set **Store Management** > **Store Settings** > **Tax** > **valueAddedTaxEnabled** to `true` to enable VAT. For more details, refer to [Set Up Tax Integration Using SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/tax-integration-via-spi.html). **Version:** 2.3.4 ## Tags ### Tax Calculation SPI [Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/tax-calculation-spi/tax-calculation-spi-oas-public.yaml) Merchant SPI to calculate taxes for a transaction according to the rules defined in the tax engine of the merchant's system. APIs include tax calculation, getting tax exemptions, and downloading tax rates for offline transactions. ### Configuration 1. **Store Management** > **Integration** > **Custom API Connectors** > **Create** * **API KEY:** TAX\_SERVICE with authentication details and URL Base. * All the APIs defined below will use this URL base; only the last keyword will change. 2. Set **Store Management** > **Store Settings** > **Tax** > **valueAddedTaxEnabled** to `true` to enable VAT. For more details, refer to [Set Up Tax Integration Using SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/tax-integration-via-spi.html). ## Operations ### POST Calculate tax. `POST /merchant/spi/sample/endpoint/taxEngine/calculateTax` Operation ID: `calculateTax`. Tags: Tax Calculation SPI. Calculate the tax based on the rules defined in the merchant's system. The request includes a list of products, tax exemptions to be applied if any, and the addresses (originating and destination) so that the correct tax rates can be applied. #### Request body Media type: `application/json`. Schema: `SpiTaxCalculationRequest`. #### Responses * **default** Default response. Media type: `application/json`. Schema: `SpiTaxResponse`. ### GET Download tax rates. `GET /merchant/spi/sample/endpoint/taxEngine/downloadTaxRates` Operation ID: `downloadTaxRates`. Tags: Tax Calculation SPI. Download tax and VAT rates into the POS system. This integration enables POS to retrieve accurate tax and VAT rates for offline transactions. The SPI supports optional query parameters such as `countryCode`, `state`, `city`, and `postalCode`, which allow for precise tax rate retrieval. The expected response format is a plain string in CSV, containing the relevant tax and VAT rates. For more detailed information, including sample requests and responses, refer to [Set Up Tax Integration Using SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/tax-integration-via-spi.html) #### Parameters * `countryCode` (query, string) * `state` (query, string) * `city` (query, string) * `postalCode` (query, string) #### Responses * **default** Default response. Media type: `application/json`. Schema: `DownloadTaxRatesResponse`. ### POST Finalize tax submission. `POST /merchant/spi/sample/endpoint/taxEngine/finalizeTaxSubmission` Operation ID: `finalizeTaxSubmission`. Tags: Tax Calculation SPI. Finalize the taxes applied to sale transactions. This is an optional SPI. It provides a list of products and applied taxes to the tax engine, and the orderId associated with the transaction. #### Request body Media type: `application/json`. Schema: `SpiTaxSubmissionRequest`. #### Responses * **default** Default response. Media type: `application/json`. Schema: `SpiPSResponse`. ### GET Retrieve tax exemptions. `GET /merchant/spi/sample/endpoint/taxEngine/getTaxExemptions` Operation ID: `getTaxExemptionList`. Tags: Tax Calculation SPI. Retrieve the list of tax exemptions supported on the merchant's side. This is an optional SPI and applicable only for tax regions and not applicable for VAT. The following optional fields can be provided in the response: TaxClasses, CountryCode, State, City, and Postal Code, such that the tax exemption is applicable as per the provided values. For example: If a tax exemption is provided with State = CA, then that tax exemption is assumed to be applied only for CA state. If an exemption can be applied regardless of state, country, or particular tax class, these fields in the response don't need to be populated. We mark them as 'ANY' denoting it can be applied without any rules or restrictions. #### Responses * **default** Default response. Media type: `application/json`. Schema: `SpiTaxExemptionResponse`. ### GET Verify tax engine. `GET /merchant/spi/sample/endpoint/taxEngine/verify` Operation ID: `verify`. Tags: Tax Calculation SPI. Verify that the SPI Tax Engine is available and requests can be sent. If the verify API is implemented, it is checked when verifying the feed source for offline taxes. If it is not implemented, we let it pass through and try to download tax rates. #### Responses * **default** Default response. Media type: `application/json`. Schema: `SpiPSResponse`. ## Schemas ### SpiTaxCalculationRequest * `cartId` (_string_, required) Unique identifier for the cart. * `editOrderId` (_string_) Order ID for the order being edited. * `taxBuckets` (_array of SpiTaxBucket_, required) All products that require tax calculations are grouped based on their origin and destination addresses, and provided in these tax buckets, along with any applicable tax exemptions. ### SpiTaxResponse * `errorMessage` (_string_, nullable) Error message shown to the user. Example: `Invalid request. Please check the request and try again.`. * `errorCode` (_string_, nullable) Error code shown to the user. Example: `INTERNAL_ERROR`. * `taxItems` (_array of TaxOrVatRecord_, required) List of products and their tax rates. * `error` (_boolean_) ### DownloadTaxRatesResponse * `errorMessage` (_string_, nullable) Error message shown to the user. Example: `Invalid request. Please check the request and try again.`. * `errorCode` (_string_, nullable) Error code shown to the user. Example: `INTERNAL_ERROR`. * `taxRates` (_string_, required) Contains the tax or VAT rates in CSV format. The first line must contain the column headers, and subsequent lines must have the corresponding tax or VAT rate values. Column names are case-sensitive and must adhere to the specified format. All required columns, their specifications, and a sample response are available in the documentation: [Set Up Tax Integration Using SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/tax-integration-via-spi.html). * `error` (_boolean_) ### SpiTaxSubmissionRequest * `cartId` (_string_, required) Unique identifier for the cart. * `editOrderId` (_string_) Order ID for the order being edited. * `orderId` (_string_) The order ID corresponding to the transaction which involved the tax calculations with the merchant's tax engine. * `taxBuckets` (_array of SpiBucket_) The list of tax buckets which include products , their tax rates, source and destination addresses and tax exemptions if any. ### SpiPSResponse * `errorMessage` (_string_, nullable) Error message shown to the user. Example: `Invalid request. Please check the request and try again.`. * `errorCode` (_string_, nullable) Error code shown to the user. Example: `INTERNAL_ERROR`. * `error` (_boolean_) ### SpiTaxExemptionResponse * `taxExemptions` (_array of SpiTaxExemption_) List of tax exemptions that are supported by the Merchant's tax engine and can be used for tax calculations.Tax exemptions are optional, can have empty response. ### SpiTaxBucket All products that require tax calculations are grouped based on their origin and destination addresses, and provided in these tax buckets, along with any applicable tax exemptions. * `products` (_array of TaxProduct_, required) List of Products that have the same originating and destination address. * `taxExemptions` (_array of SpiTaxExemptionRequest_, nullable) The list of tax exemptions to be applied during tax calculation, this is optional. It is applicable only for tax regions and not applicable for VAT. * `originStoreId` (_string_, nullable) The originating store ID where the transaction is occurring. * `fromAddress` (_SPIAddress_, required) * `toAddress` (_SPIAddress_, required) ### TaxOrVatRecord List of products and their tax rates. * `amount` (_number_, required) Product Amount. * `productId` (_string_, required) Product ID. * `quantity` (_integer (int32)_, required) Product Quantity. * `orderItemId` (_string_, required) Order item ID of the product. This must match the orderItemId sent in the request. Used as a line identifier to resolve conflicts when two line items have the same productId. * `description` (_string_, nullable) Product name. * `taxClass` (_string_, nullable) Tax class of this product. Can be used for tax calculation. It will be sent if the product feed has it. * `taxRecord` (_SpiTax_) * `vatRecord` (_SpiVat_) ### SpiBucket The list of tax buckets which include products, their tax rates, source and destination addresses, and tax exemptions if any. * `products` (_array of TaxProduct_, required) List of Products that have the same originating and destination address. * `taxExemptions` (_array of SpiTaxExemptionRequest_, nullable) The list of tax exemptions to be applied during tax calculation, this is optional. It is applicable only for tax regions and not applicable for VAT. * `originStoreId` (_string_, nullable) The originating store ID where the transaction is occurring. * `fromAddress` (_SPIAddress_, required) * `toAddress` (_SPIAddress_, required) * `records` (_array of TaxOrVatRecord_, required) List of products and their tax rates. ### SpiTaxExemption List of tax exemptions that are supported by the merchant's tax engine and can be used for tax calculations. Tax exemptions are optional and can have an empty response. * `taxExemptCode` (_string_, required) Tax exemption code to be applied, for example, 100, 05, A, or CED. * `taxExemptName` (_string_, required) Tax exemption long name, for example, RESALE or TRIBAL GOVERNMENT. * `taxExemptionRate` (_number_, required) Tax exemption rate percentage. * `taxType` (_string_, nullable) Tax Type. Allowed values: `CLASS`, `CITY`, `DISTRICT`, `COUNTY`, `STATE`, `COUNTRY`, `ITEM_OVERRIDE`, `STORE_OVERRIDE`, `SPECIAL`. * `taxClasses` (_array of string_, nullable) Tax classes to which the exemption applies. * `countryCode` (_string_, nullable) Country Code where the exemption is applicable. * `state` (_string_, nullable) State where the exemption is applicable. * `city` (_string_, nullable) City where the exemption is applicable. * `postalCode` (_string_, nullable) Postal Code where the exemption is applicable. ### TaxProduct List of Products that have the same originating and destination address. * `amount` (_number_, required) Product Amount. * `productId` (_string_, required) Product ID. * `quantity` (_integer (int32)_, required) Product Quantity. * `orderItemId` (_string_, required) Order item ID of the product. This must match the orderItemId sent in the request. Used as a line identifier to resolve conflicts when two line items have the same productId. * `description` (_string_, nullable) Product name. * `taxClass` (_string_, nullable) Tax class of this product. Can be used for tax calculation. It will be sent if the product feed has it. ### SpiTaxExemptionRequest The list of tax exemptions to be applied during tax calculation, this is optional. It is applicable only for tax regions and not applicable for VAT. * `customerName` (_string_, required) Customer name for customer having tax exemption applied. * `cardNumber` (_string_, required) Customer tax exemption card number. * `taxExemptCode` (_string_, required) Tax exemption code to be applied, for example, 100, 05, A, or CED. * `taxExemptName` (_string_, required) Tax exemption long name, for example, RESALE or TRIBAL GOVERNMENT. * `taxType` (_string_, nullable) Tax Type. Allowed values: `CLASS`, `CITY`, `DISTRICT`, `COUNTY`, `STATE`, `COUNTRY`, `ITEM_OVERRIDE`, `STORE_OVERRIDE`, `SPECIAL`. ### SPIAddress The full address of the destination of transaction. * `firstName` (_string_) Customer first name saved for address. * `lastName` (_string_) Customer last name saved for address. * `addressLine1` (_string_, required) Address Line 1. * `addressLine2` (_string_) Address Line 2. * `city` (_string_, required) City. * `state` (_string_) State. * `postalCode` (_string_, required) Postal Code. * `countryCode` (_string_, required) Country Code. * `phone` (_string_) Phone. * `storeId` (_string_) Store ID if it is store address. * `emailAddress` (_string_) Customer Email Address. ### SpiTax Tax details for this product. Populate either tax or VAT. * `totalTax` (_number_, required) Total tax. Required in case of tax countries. Maps to productList.productTax.totalTax in Order TLOG JSON. * `taxRates` (_array of ItemTax_, required) Tax rates. Maps to productList.productTax.taxRates\[\] in Order TLOG JSON. * `totalExemptionAmount` (_number_) Total tax exemption amount that was applied. Maps to productList.productTax.taxExemption in Order TLOG JSON. ### SpiVat VAT details for this product. Populate either tax or VAT. * `totalVat` (_number_, required) Total VAT. Required in case of VAT countries. Maps to productList.productTax.valueAddedTax in Order/Cart. * `vatRates` (_array of ItemTax_, required) VAT rates. Maps to productList.productTax.vatRates\[\] in Order TLOG JSON. * `totalExemptionAmount` (_number_, required) Total tax exemption amount that was applied. Maps to productList.productTax.taxExemption in Order TLOG JSON. ### ItemTax Individual tax rates and their details. After the sale transaction, the TLog JSON will contain the product's tax rates corresponding to this class in productList\[\].productTax.taxRates and orderProductList\[\].productTax.taxRates. * `taxRate` (_number_, required) % tax/vat rate. * `taxAmount` (_number_, required) Sum of tax amounts of a particular type (group of TaxType, TaxClass, TaxName, TaxRate) at the time of purchase. This represents the total line tax and should be calculated considering the quantity sent in the request. * `taxType` (_string_, required) Indicates tax type, such as COUNTRY, CITY, or STATE. Allowed values: `CLASS`, `CITY`, `DISTRICT`, `COUNTY`, `STATE`, `COUNTRY`, `ITEM_OVERRIDE`, `STORE_OVERRIDE`, `SPECIAL`. * `taxCode` (_string_, required) Tax identifier. This is a unique identifier for tax rate per item. * `taxClass` (_string_, required) Tax class to which this tax rate belongs, for example, 1025 or T1C. * `perUnitTaxAmount` (_number_, required) The tax amount per unit in the case of multiple quantities of the product. * `highPrecisionTaxAmount` (_number_, nullable) Tax amount of a particular type (group of TaxType, TaxClass, TaxName, TaxRate) at the time of purchase with high precision (Scale / Number of decimal digits = 5). Required for Portugal region. * `taxName` (_string_, nullable) Tax name, for example, Jurisdiction, MTA, BTW Hoog, or BTW Laag. * `isExempt` (_boolean_) Indicates whether tax is exempted. Default: `false`. * `taxExemptCode` (_string_, nullable) Tax Exemption Identifier to be provided in case this tax was exempted. * `taxExemptionAmount` (_number_, nullable) The tax amount value that was exempted. * `countryCode` (_string_, required) Country code. * `state` (_string_, required) State. * `postalCode` (_string_, required) Postal code.