Specification

In synchronous integration, VTEX's Checkout API triggers a request to the external tax service API whenever a shopper's cart changes, such as adding or removing items.

To learn more about how to implement a client to connect your tax calculation provider to VTEX's APIs, check the Tax Service recipe and example.

The timeout for the request is five seconds. There is no retry on a timeout. If the external service that responds to the request repeatedly times out, the store won't be able to complete the order. If this integration is active, it applies to all stores in that account.

You must activate the tax integration by configuring the orderForm, an object that stores contextual information about the order. This data is essential to the checkout process of the order.

Check the flow of orderForm configuration below:

To activate the tax integration, first obtain the current orderForm settings using the Get orderForm configuration endpoint.

In the endpoint response, the taxConfiguration object has the tax information that must be updated, as in the example below:

Then, the Checkout settings must be updated using the Update orderForm configuration endpoint.

In the taxConfiguration object, it is important to update the following fields.

The isMarketplaceResponsibleForTaxes feature isn't compatible with stores that have Multilevel Omnichannel Inventory implemented.

Here is an example of the taxConfiguration object with the expected information:

You must send the entire orderForm in the request body for the Update orderForm configuration endpoint.

After successfully submitting the request, the Tax API integration becomes active in synchronous mode.

When a purchase is made in a store, the location from which the order is shipped matters for tax calculation purposes. Because of this, when items from White Label Sellers are part of an order, tax configuration for the marketplace (seller 1) is not taken into account for those items. Each seller must have its own tax service configuration in order for this type of integration to function properly.

The external tax calculation service must provide an endpoint, such as the https://sandbox-rest.avatax.com/api/v2/transactions/create example, that will receive a POST request. In this request, Checkout provides a body in a specific format. This means that either the endpoint must be prepared to receive this body format, or the integration must contain a parser to adapt it to the correct format.

Here is an example of that body sent by Checkout API:

This body has the main fields:

In response to the request sent by Checkout, the external tax provider API is expected to return an array of products, each with its own array of taxes and, optionally, an array of fees. See the example below:

The following JSON represents a list of taxes associated with a particular item, with each tax defined by its name, description, and value:

In the example above, the only item in the items array has a cost of 10, and, including the calculated taxes returned by the tax calculation tool, the total value would be 10 + 3.48 + 22 = 35.48.

If no taxes apply to the items in the order, the expected response is an empty array ([]).

For the Checkout API to interpret the request body, the Content-Type must be set to application/vnd.vtex.checkout.minicart.v1+json.

Item fees

Besides taxes, the tax provider can optionally return a fees array for each item, at the same level as taxes. Use fees to separate charges that aren't taxes from the fiscal taxes applied to the item.

Taxes are fiscal or government charges that are included on invoices and in tax remittances. Fees are additional charges, usually regulatory or commercial, that shouldn't go through the same fiscal flow. For example, a deposit for returnable packaging that varies by state is a fee, not a tax. Without the fees array, the provider must return this charge as a tax, which adds it to the tax total and results in incorrect fiscal values.

The fees array is optional. If the provider doesn't return it, Checkout behaves as it does with taxes only, and existing integrations don't need to change.

When the provider returns fees, Checkout handles them as follows:

• Each fee is added to the item's priceTags with the FEE@{name} prefix. Taxes use the TAXHUB@{name} prefix.
• The fee values are added to a Fee totalizer in the cart and order, separate from the CustomTax totalizer that adds up the taxes.

Each object in the fees array has the same fields as the objects in the taxes array. See the example below:

In the example above, considering an item that costs 10, the total value would be 10 + 0.4 + 0.05 = 10.45. The tax value (0.4) is added to the CustomTax totalizer, and the fee value (0.05) is added to the Fee totalizer.

Jurisdiction fields

If you use Avalara as your tax calculation provider, response bodies can also include the following fields, which refer to the different jurisdictions that may apply according to location.

These fields are also read by Checkout and added to the priceTag.

Below is an example of values that may be contained in these fields, and you can download all the jurisdictions and respective codes used by Avalara.

By following these guidelines and leveraging the provided examples, you can incorporate tax integration into your VTEX platform.