# Integrate tax

Calculating tax is a core part of any commerce system. You can choose to calculate taxes internally 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 [Connect](/connect) with commercetools Frontend [extensions](/frontend-development/extensions.md). The second pattern uses Connect and [API Extensions](/api/projects/api-extensions.md).

In addition, we will also share some best practices around managing external taxes on a [Cart](/search.md?urn=ctp:api:type: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](/tutorials/tax-integration.md#the-bff-pattern), [Tax Categories](/api/projects/taxCategories.md) 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](/api/general-concepts.md#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](/tutorials/tax-integration.md#the-api-extensions-pattern), in some cases the tax category should be added as an [Attribute](/search.md?urn=ctp:api:type: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](/api/projects/custom-fields.md) on the [Customer](/api/projects/customers.md) 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:

![Tax integration with BFF](https://docs.commercetools.com/tutorials/images/tax-integration-with-bff-approach.png)

This approach uses the following components:

- **A BFF with the custom tax calculation implementation**: this service can be built using the commercetools Frontend [extensions](/frontend-development/extensions.md).
- **A Subscriptions-based Order synchronizer**: this component can be built and hosted on Connect. It can subscribe to and react to [Messages](/api/projects/messages.md) triggered on Order creation and updates.

### The API Extensions pattern

Next, let's take a look at the architectural overview of the [API Extensions](/api/projects/api-extensions.md) pattern:

![Tax integration with API Extensions](https://docs.commercetools.com/tutorials/images/tax-integration-with-api-extensions.png)

This approach uses the following components:

- **A tax calculation service using [API Extensions](/api/projects/api-extensions.md)**: this component can be built and hosted on Connect. It exposes the endpoint configured for the API Extension.
- **Subscriptions-based Order synchronizer**: this component can be built and hosted on Connect. It can subscribe to and react to [Messages](/api/projects/messages.md) triggered on Order creation and updates.

## Cart configuration

Next, let's explore the [Cart](/search.md?urn=ctp:api:type: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 Cart's [TaxMode](/search.md?urn=ctp:api:type:TaxMode) to `External` or `ExternalAmount`. For a description of each mode, see [Tax modes](/api/carts-orders-overview.md#tax-modes).

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](/search.md?urn=ctp:api:type:Cart).

Update the [TaxedPrice](/search.md?urn=ctp:api:type:TaxedPrice) of the [Line Items](/api/carts-orders-overview.md#line-items):

- [Set LineItem TaxRate](/api/projects/carts.md#set-lineitem-taxrate).
- [Set LineItem TaxAmount](/api/projects/carts.md#set-lineitem-taxamount).
- [Set CustomLineItem TaxRate](/api/projects/carts.md#set-customlineitem-taxrate).
- [Set CustomLineItem TaxAmount](/api/projects/carts.md#set-customlineitem-taxamount).

Apply the correct tax amounts and rates on [Shipping Methods](/api/projects/shippingMethods.md):

- [Set ShippingMethod TaxAmount](/api/projects/carts.md#set-shippingmethod-taxamount).
- [Set ShippingMethod TaxRate](/api/projects/carts.md#set-shippingmethod-taxrate).

## Tax Connector

To recap, tax integrations using the BFF pattern rely on commercetools Frontend [extensions](/frontend-development/extensions.md) and Connect.

For the tax calculation component, use an [action extension](/frontend-development/developing-an-action-extension.md) to call the external tax system for calculating the tax on a [Cart](/search.md?urn=ctp:api:type:Cart).

For the Order-synchronization component, Connect provisions the infrastructure needed to host the tax connector. It also provides a [postDeploy](/connect/automation-scripts.md#postdeploy) feature that helps during deployment creation to automate the configuration of the [API Extensions](/api/projects/api-extensions.md) and [Subscriptions](/api/projects/subscriptions.md).

To get started with [Connect](/connect), see our guides for [Getting started](/connect/getting-started.md) and [Development](/connect/development.md).

## External tax providers

[Avalara](https://marketplace.commercetools.com/integration/avalara-avatax), [Vertex](https://marketplace.commercetools.com/integration/vertex-indirect-tax), and [TaxJar](https://www.taxjar.com/) 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](/api/projects/api-extensions.md#extensiontrigger) 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](/frontend-development/extensions.md).

## Conclusion

In this guide, you learned about two common architectural approaches for implementing external tax calculation: the [BFF pattern](/tutorials/tax-integration.md#the-bff-pattern) and the [API Extensions pattern](/tutorials/tax-integration.md#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.

## Related pages

- [Area overview page with navigation](/tutorials.md)
- [Previous page: Populate a Store-specific external search](/tutorials/store-specific-external-search.md)
- [Next page: Integrate email](/tutorials/connect-email-integration.md)
- [Search documentation and API specs](/search.md)