Salesforce Commerce Tax API

Calculate taxes for line items and get tax information for specified products by using the Salesforce Commerce Tax APIs. You can execute these requests outside cart and checkout pages so that you can show tax calculations elsewhere in your store.

To calculate taxes for line items in a Commerce webstore, make a POST request to the Commerce Webstore Calculate Taxes resource. This request executes the same tax calculations used by the Cart Calculate API (CCA). However, using the Connect API resource rather than CCA means tax calculations can be done outside of cart and checkout.

For a POST request, specify the Calculate Taxes Input request body. This request body requires a list of line items grouped by shipping address. The shipping address includes the ISO code of the country and state. The request associates line items with the buyer account or guest profile ID (from effectiveAccountId) and the webstore ID (from the URL).

If your store supports multiple currencies, the POST request must also specify the currencyIsoCode to use for tax calculation (for example, USD). If unspecified, the default value is the default country for the webstore.

You can use the boolean property calculatebyTaxClass to determine whether taxes are calculated based on tax class (true) or not (false). Tax classes are important if your store supports the Japanese Consumption Tax (JCT), which imposes different tax rates on different types of products. The rate is 10% for most goods and services, but it‘s 8% for certain food, beverage, and newspaper products. Tax calculation rounds JCT amounts by the total JCT amount per tax class rather than per product.

The response body for the POST request, Calculate Taxes, indicates whether the tax calculation was successful, and, if it wasn‘t successful, lists any error messages. The property taxLocaleType indicates whether the webstore uses gross taxation, where product prices include tax, or net taxation, where prices don’t include tax.

The tax information returned includes the sum of taxes for all line items and tax details, including amounts, adjustments, and rates, broken down by line item. If calculatebyTaxClass was set to true, the response body also returns details about the taxation amount by tax class.

To get tax rates for a product based on the webstore, shipping location, and buyer account or guest profile ID, make a GET request to the Commerce Webstore Taxes resource.

This resource is for stores that use the manual Salesforce tax solution and gross taxation, or a custom extension. If your store uses the Salesforce tax solution with a third-party tax calculation service like Stripe, only mocked data returns from GET requests. The manual solution is suitable if you have a simple gross tax situation. In any case, consult with a tax expert when setting up taxes for your store.

Specify the webstore and product IDs in the resource URL. For example, https://yourInstance.salesforce.com/services/data/v62.0/commerce/webstores/0ZEPI0000000j8Q4AQ/taxes/​products/01tPI0000003fLBYAY.

In the request parameters, set countryIsoCode to indicate the destination country or territory for the shipped product, rather than the origin of the order. This code determines the applicable geo country tax rate. If unspecified, the default value is the default country for the store. If you configured tax rates for states or provinces within the country or territory, also set the optional stateIsoCode parameter. For both parameters, match the ISO codes with codes defined within your org’s state and country picklists. For a list of ISO codes, see Standard Countries and Territories for Address Picklists.

The GET request also requires the effective​AccountId parameter, which represents the buyer account or guest buyer profile ID for which the request is made. If unspecified, the default value is determined from context.

The response body for GET returns the tax locale type of the store (Gross or Net) and a map of the product ID to its taxation details.

To understand the Tax APIs, consider the steps involved in a basic scenario for tax calculation and rate retrieval. This scenario doesn’t include the entire Tax API functionality.

First, confirm that your Commerce administrator configured taxes rates for your store. They can use the manual tax solution, the Salesforce tax solution with Stripe, or a custom extension. The Calculate Taxes POST API is compatible with each option, but the Taxes GET API isn’t compatible with the native Stripe integration.

When a buyer adds products to their cart, the platform groups these items by shipping address, which includes necessary details like country and state ISO codes. To show taxes right away when the cart is viewed, you can send a POST request to the Salesforce Commerce Webstore Calculate Taxes resource. In the request, include line items, shipping details, and the currency ISO code. The API calculates taxes based on this data and returns detailed tax amounts, adjustments, and rates for each line item.

If your store uses the manual tax solution with gross taxation, you can enhance the shopping experience by displaying tax rates on additional pages outside of cart and checkout, like the Product Detail page. For example, make a GET request to the Commerce Webstore Taxes resource. In your request, include the IDs for the webstore, product, and account. Also include the buyer’s country or territory and state or province, if applicable. Then, parse the tax rate of the product from the response. You can use this information to calculate the product price before taxes and display this value on the Product Detail page beneath the gross price.