Tax calculations are a crucial aspect of any digital commerce platform. Composable Commerce provides a flexible and robust system for managing taxes based on Tax Categories and Shipping Methods.
A Tax Category serves as a container for related Tax Rates. It groups Tax Rates together to apply consistent taxation across Products or Shipping Methods. You can think of it as a category of Products or Shipping Methods that are taxed similarly. For example, a business may have categories such as "Standard," "Reduced," or "Tax-Free-Food." You assign a single Tax Category to the Product (not the Product Variant) and the Shipping Method.
Tax Categories support a one-to-many relationship with Tax Rates. This allows for scenarios where a country uses a consistent Tax Category, but individual states or regions apply different rates. Different Tax Categories can be applied independently to each Line Item in a Cart.
Key concepts
The tax system in Composable Commerce is composed of three core types:
- Tax Category: a container for Tax Rates, assigned to Products and Shipping Methods.
- Tax Rate: the tax percentage for a specific country and optionally a state or region. It is typically based on the delivery address, but depending on your tax rules, you might need to consider the origin address as well. The
includedInPriceflag indicates whether the tax is already included in the price.- SubRate: a component of a compound Tax Rate, such as the federal, state, and local portions of a combined tax. All SubRates must sum to the Tax Rate.
Example Tax Category JSON
{
"name": "New Tax Category",
"rates": [
{
"name": "Combined Rate",
"amount": 0.1,
"includedInPrice": false,
"country": "US",
"state": "CA",
"subRates": [
{
"name": "State Tax",
"amount": 0.06
},
{
"name": "County Tax",
"amount": 0.04
}
]
}
]
}
How it works
- Define Tax Categories: create Tax Categories representing different taxation treatments for Products or Shipping Method. Give them meaningful names and descriptions.
- Define Tax Rates: within each Tax Category, create Tax Rates for the countries and regions where you sell. Specify the tax amount (for example, 0.1 for 10%), and whether the tax is included in the price. Use SubRates to define compound taxes if needed.
- Assign Tax Category to Products: when creating or updating a Product, assign the appropriate Tax Category.
- Calculations at Checkout: Composable Commerce uses the assigned Tax Category and its associated TaxRates to calculate taxes during checkout. It uses the customer's shipping address to determine the applicable Tax Rate.
Example: Manage Australian taxes and non-taxable entities
Australia has a flat 10% Goods and Services Tax (GST) on most goods and services. However, there are some exceptions, such as basic food items, medical services, and educational courses, which are generally GST-free.
To manage this scenario, we will need to create two Tax Categories. One for Australia-GST and another for Australia-GST-Free.
{
"id": "b69bf78a-36cb-4b62-9f0a-462a0194b7be",
"version": 1,
"createdAt": "2024-11-28T07:40:50.712Z",
"lastModifiedAt": "2024-11-28T07:40:50.712Z",
"lastModifiedBy": {
"isPlatformClient": true,
"user": {
"typeId": "user",
"id": "c950c084-f5d0-4a42-8761-229d5c7a8598"
}
},
"createdBy": {
"isPlatformClient": true,
"user": {
"typeId": "user",
"id": "c950c084-f5d0-4a42-8761-229d5c7a8598"
}
},
"name": "Australia-Gst",
"description": "Australian GST",
"rates": [
{
"name": "GST",
"amount": 0.1,
"includedInPrice": true,
"country": "AU",
"id": "-xBFd049",
"subRates": []
}
]
}
Address matching
A challenge in tax calculation arises when shipping addresses include a state (like
VIC or NSW) but the Tax Rate is defined without a state. You can see in our example JSON above that we have the Country AU, but no State is specified. In this situation, if a Cart's shipping address specifies a state, and the Tax Rate does not, there will be no exact match, and tax calculation may fail.We have three options to overcome this.
| Option | Description | Pros | Cons |
|---|---|---|---|
Option 1: Bypass the state field and use the region field from a corresponding Address object as a workaround | Leaves the state field in the shipping address blank and stores the Australian state/territory information in the region field instead. The Tax Category needs only a single Australian Tax Rate without specifying the State. | No changes to Tax Categories required. | Repurposes the region field for state/territory information, deviating from its intended use. Additionally, some integrated systems might require a valid state value, necessitating custom mapping between the region and the external state field in your integration logic. The frontend will need to know that it should use the region field instead of the state field. |
| Option 2: Custom Field for Australian states | Creates a Custom Field on the shipping address specifically for the Australian state/territory. The standard state field is left blank. | No changes to Tax Categories required. | The frontend will need to know that it should use this new Custom Field instead of the state field. Other systems consuming the address may be required to map this Custom field as the state field. |
| Option 3: State-specific Tax Rates | Creates individual Tax Rates within the Australian Tax Category for each of the six states and ten territories. The tax calculation engine then automatically applies the correct rate based on the state field in the shipping address. | Most precise and compliant tax calculations based on state-level tax variations. | Requires setting up and maintaining separate Tax Rates, which can take extra time setting up initially but simplifies ongoing maintenance and ensures accuracy. |
When working with tax data, ensure that both State values in the Cart and Tax Rate fields use consistent capitalization. Inconsistent capitalization may lead to mismatches and errors in tax calculation.
Complex taxes and third-party tax integration
For countries with complex tax systems, such as the USA with over 10,000 tax jurisdictions, integrating a third-party tax engine is often essential. Composable Commerce supports this through its external tax modes. For a complete guide on integrating a tax provider, see Integrate tax.
Test your knowledge
Next module
Nice work on finishing the Images and Assets module! You're now ready to proceed with the Model your product catalog learning path by diving into the next module. See you there!