This is the early access documentation preview for Custom Views. This documentation might not be in sync with our official documentation.

Tax integration

Calculating tax is a core part of any commerce system. You can choose to calculate taxes internally with Composable Commerce or externally using a third-party tax calculation service. The option you choose generally depends on how complex the taxes are in the areas where you sell your products. For example, in the United States or Canada, each state or province may have different tax rates. In addition, tax rates can differ depending on the products being sold. In complex tax situations, merchants typically choose an external tax provider to ensure the correct taxes are applied.

In this guide, you'll learn about two different architectural patterns to consider when integrating a third-party tax calculation service into your Project. The first pattern uses commercetools Connect with commercetools Frontend extensions. The second pattern uses commercetools Connect and API Extensions.

In addition, we will also share some best practices around managing external taxes on a Cart, as well as some general tips on working with external tax providers.

Project setup

When working with an external tax provider, provide them with all the relevant information to ensure taxes are calculated correctly.

For example, you may need to provide:

The type of products being sold
The distribution method for the product, such as delivery or pick-up
The tax-exempt status of the purchaser

Next, we'll guide you through some Project configuration settings that enable you to send the necessary information to the external tax provider.

Product data model

Products can be taxed differently based on their type, intended use, or other characteristics. For example, clothing might be exempt from sales tax in some regions while electronic items might be taxed at a standard rate. Another example might be a luxury tax applied to high-end products.

To ensure taxes are properly calculated, you'll need to associate each product in your catalog to a specific Tax Category as defined by the country or region where the product is being sold. Oftentimes, the manufacturer or supplier of the product can provide the applicable tax category.

If you use the BFF pattern, Tax Categories can typically be used to store the tax category of the product. The extension (which integrates with the external tax provider) can utilize Reference Expansion on the Tax Category within the Cart to obtain the category code of the product. Once the category code is retrieved, it can be passed along with the Line Item.

If you use the API Extensions pattern, in some cases the tax category should be added as an Attribute on a Product. For example, if the Product Variants have different tax categories, an Attribute to contain the tax category should be used. This also applies if your product catalog requires more than the maximum limit of 100 Tax Categories. The tax category code is then included in the Variant representation on the Line Item in the Cart.

Customer Profile

Some products might be tax-exempt for specific buyers (for example, a non-profit organization or government entity). In this case, you can store the tax-exempt information using Custom Fields on the Customer profile. Some external tax providers require an exemption certificate number, while others manage the certificate and utilize an identifier to reference to the customer. When a tax-exempt Customer creates a Cart, the tax exemption data can be added as Custom Fields to store the information needed to pass via the integration.

Tax integration architecture

We recommend choosing either the BFF or API Extensions pattern for integrating external tax providers. Using the API Extensions pattern can be a good option in the beginning, as it requires less effort for your initial implementation. The approach can later be changed to use the BFF pattern, if necessary; for example, to build differentiated customer flows.

The BFF pattern

Let's start with a high-level overview of all components and interactions involved in a tax integration with the BFF architecture pattern:

This approach uses the following components:

A BFF with the custom tax calculation implementation: this service can be built using the commercetools Frontend extensions.
A Subscriptions-based Order synchronizer: this component can be built and hosted on commercetools Connect. It can subscribe to and react to Messages triggered on Order creation and updates.

The API Extensions pattern

Next, let's take a look at the architectural overview of the API Extensions pattern:

This approach uses the following components:

A tax calculation service using API Extensions: this component can be built and hosted on commercetools Connect. It exposes the endpoint configured for the API Extension.
Subscriptions-based Order synchronizer: this component can be built and hosted on commercetools Connect. It can subscribe to and react to Messages triggered on Order creation and updates.

Cart configuration

Next, let's explore the Composable Commerce Cart configuration options that you will use when integrating external taxes. We will also list the update actions you need to manage the tax integration.

TaxMode

To use an external tax provider, set the TaxMode using the taxMode property of the Cart to one of the following:

Use External when the external tax provider provides the percentage for calculation rather than calculating the cost.
Use ExternalAmount when the external tax provider calculates the tax amount to be applied to the Cart.

To eliminate any possible rounding discrepancies between the commercetools Cart and the tax provider reporting, we recommend that you use ExternalAmount.

Update actions

Use the following update actions to apply external tax on a Cart.

Update the TaxedPrice of the Line Items:

Apply the correct tax amounts and rates on Shipping Methods:

Tax Connector

To recap, tax integrations using the BFF pattern rely on commercetools Frontend extensions and commercetools Connect.

For the tax calculation component, use an action extension to call the external tax system for calculating the tax on a Cart.

For the Order-synchronization component, commercetools Connect provisions the infrastructure needed to host the tax connector. It also provides a postDeploy feature that helps during deployment creation to automate the configuration of the API Extensions and Subscriptions.

To get started with commercetools Connect, see the our guides for Getting started and Development.

External tax providers

Avalara, Vertex, and TaxJar are some of the platforms that provide tax solutions to businesses. Each of them provides a different set of features to meet specific requirements.

External tax systems generally have API requests-based pricing models and have limitations on the number of API calls. Therefore, we recommend that you review the sales channel checkout funnel and use a conditional API Extensions trigger to reduce the number of times the tax system is called for tax calculations.

If the external tax system provides an address validation service, you can integrate this using commercetools Frontend extensions.

Conclusion

In this guide, you learned about two common architectural approaches for implementing external tax calculation: the BFF pattern and the API Extensions pattern. Going forward, we recommend that you consider the limitations of external tax providers, such as API call limitations. In addition, be sure to verify your Cart configuration is correct to ensure taxes are implemented and displayed properly.