If you use synchronous tax service integration, you might find some limitations:

• Timeout for the request is five seconds.
• There is no retry in case of timeout.
• If the external service that responds to the request times out constantly, the store will not be able to finish the order.
• If this integration is active, it applies to all stores in that account.

For stores in which there are often up to hundreds of items in a cart, like some B2B operations, this flow can become inefficient and expensive. In this case, consider using asynchronous integration.

Asynchronous integration is an alternative that offers a better user experience, as it ensures that the flow will always have the taxes at the right time, although it depends directly on the resilience of third parties.

By definition, this type of integration allows other processes to move forward while it waits for a response from the tax engine. Thus, the system will not respond with a timeout even if it takes more than 5 seconds to respond.

Instead of calling the external tax service API for each item added to the cart, asynchronous integration will send just one request resulting in less data being processed, and thus checkout becomes faster and more efficient. That request can be triggered, for instance, by an event in the checkout UI.

To use asynchronous integration, Checkout can not be configured to handle the External Tax Services. This configuration should only be done for synchronous integration. To use asynchronous integration, make sure that the response from the Checkout Configuration API has the taxConfiguration object with the value null. If not, use the Checkout Configuration UPDATE request to make it null.

The asynchronous call to the tax engine does not require any configuration. It must be implemented by the store, as described in this recipe. It is usually triggered by an event or button in the checkout UI.

To query the tax engine, the implementation must follow this flow:

• Get the orderForm.
• Calculate taxes (or get calculation from the external provider).
• Submit response with taxes.

Getting the orderForm

To obtain the orderForm, the implementation must use the following request:

• Method: GET
• URL: https://{accountName}.{environment}.com.br/api/checkout/pub/orderForm/{orderFormId}?disableAutoCompletion=true

The disableAutoCompletion=true parameter is necessary to ensure that the requested orderForm won’t be recalculated but delivered exactly as it was at the time of the request.

Although the route is public (/pub), it is necessary to use credentials (appKey and appToken) with permission to access the cart data to obtain the unmasked data.

Calculating taxes and sending the response

Having obtained the orderForm, the implementation must calculate the appropriate taxes, or get the appropriate calculations from the external provider, and send the following information in the response:

• itemTaxResponse: an array of items (SKUs), each containing an array of applicable taxes.
• miniCartRequest: an object containing the items, delivery address, buyer data, orderForm ID, and trade policy of the cart receiving the taxes.

Taxes should be sent to the following endpoint:

• Method: POST
• URL: https://{accountName}.vtexcommercestable.com.br/api/checkout/pvt/orderForms/taxes

Below is an example body.

This request requires the appKey and appToken credentials.

Validating taxes

Note that the tax engine response includes, in addition to the taxes, the minicart that was used for the calculation. So, VTEX is able to guarantee that the calculated tax is consistent with the cart that is completing the purchase. This happens through the following algorithm:

• When the system receives the response from the tax provider, it gets the minicart that was used to calculate the taxes.
• The system generates a token for this minicart and saves it in the cart.
• When the purchase is concluded, the token is sent to the seller, who checks whether it matches the cart that is completing the purchase.
• If it is the same token, the purchase is completed, with the tax applied. If the tokens do not match, the purchase is denied.
• If the purchase is denied, there will be a 500 error in the request /transaction: “The order cannot be created. Please try again."

The implementer is responsible for the minicart. Note that it is crucial for validating taxes, so there must be an exact match with the customer's current cart.

If the system takes too long to apply the tax, you can create an order without taxes.

If the system takes too long to review the tax after changes to the cart, it will not be possible to complete the order.

Example of order object

Finally, see an example of an order object at VTEX after taxes are applied. Note that they have been included in the totals array.