# Tax Categories and Tax Rates

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](/api/projects/taxCategories.md) and [Shipping Methods](/api/projects/shippingMethods.md).

A Tax Category serves as a container for related [Tax Rates](/api/projects/taxCategories.md#taxrate). 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](/api/projects/taxCategories.md#taxcategory)**: a container for Tax Rates, assigned to Products and Shipping Methods.
- **[Tax Rate](/api/projects/taxCategories.md#taxrate)**: 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 `includedInPrice` flag indicates whether the tax is already included in the price.
  - **[SubRate](/urn?urn=ctp%3Aapi%3Atype%3ASubRate)**: 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

```json title="Example request for creating a new Tax Category"
{
  "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

1. **Define Tax Categories**: create Tax Categories representing different taxation treatments for Products or Shipping Method. Give them meaningful names and descriptions.
2. **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.
3. **Assign Tax Category to Products**: when creating or updating a Product, assign the appropriate Tax Category.
4. **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.

```json title="Example of created 10% GST Tax Category"
{
  "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](/api/types.md#addresses) 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](/api/carts-orders-overview.md#tax-modes). For a complete guide on integrating a tax provider, see [Integrate tax](/tutorials/tax-integration.md).

## 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!

Learn how to model and manage business processes by using Composable Commerce state machines. 

## Related pages

- [Area overview page with navigation](/learning-model-your-business-structure.md)
- [Previous page: Overview](/learning-model-your-business-structure/model-your-taxes/overview.md)