Documentation

Tax Categories and Tax Rates

Elevate, May 20-22-2025, Miami Beach, Florida

Learn how to set up and manage Tax Categories and Tax Rates in Composable Commerce.

  • After completing this page, you should be able to:

    • Define and differentiate between Tax Categories and Tax Rates in Composable Commerce, and explain how they interact to calculate taxes.

    • 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

    • Tax Category: a container for Tax Rates.
    • Tax Rate: specifies the tax percentage (for example, 0.13 for 13%) for a specific country and optionally a state or region. It is typically based on the destination address (where goods are shipped). However, depending on your tax rules, you might need to consider the origin address of the goods as well (where they are shipped from). For example, if you have warehouses in California and Texas, and those states have different tax rates or rules, you might need separate Tax Categories or Tax Rates to handle these scenarios.
      • SubRate: allows you to break down a Tax Rate into its component parts. This is useful for compound taxes such as VAT, which includes federal, state, and local taxes. It provides transparency in reporting and calculations. All SubRates must be the sum of the Tax Rate. Multiple SubRates can belong to a single Tax Category.
    • includedInPrice: a boolean flag indicating whether the tax is already included in the Product or Shipping Method price. This is crucial for correctly calculating net and gross prices.

    Example Tax Category JSON

    Example request for creating a new Tax Categoryjson
    {
  "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.

    Example of created 10% GST Tax Categoryjson
    {
  "id": "b69bf78a-36cb-4b62-9f0a-462a0194b7be",
  "version": 1,
  "versionModifiedAt": "2024-11-28T07:40:50.712Z",
  "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.

    OptionDescriptionProsCons
    Option 1: Bypass the state field and use the region field from a corresponding Address object as a workaroundLeaves 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 statesCreates 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 RatesCreates 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

    Sometimes tax compliance is not as simple as in the Australian case outlined above.

    Let’s take the American tax system for example. Navigating sales tax for digital commerce in the USA can feel like traversing a minefield. With over 10,000 different tax jurisdictions, each with its own rates, rules around product taxability and shipping, and even occasional tax holidays, determining the correct amount to collect can be a nightmare. Add in state-specific economic nexus laws, marketplace facilitator regulations, and the constantly evolving US tax codes, and the complexity multiplies.

    For businesses operating in the US or other countries with similarly complex tax systems, integrating an automated third-party tax engine is often essential. These systems calculate sales tax in real time across all relevant jurisdictions, accounting for exemptions and tax holidays. They also manage exemption certificates and reporting requirements, allowing businesses to focus on growth rather than the intricacies of tax compliance.

    Composable Commerce makes it possible to integrate with a third party tax engine or your own tax engine. Read more about this in our best practice guide on Tax integration.

    Test your knowledge

    Where to next?

    Great job at finishing the Model your taxes module. You covered a lot of ground!

    That brings us to the end of the Model your business structure learning path. If you haven't yet completed our other functional learning paths, we strongly recommend you complete these next. Click one of the cards below to get started. Good luck!