Tax Module

In this section of the documentation, you will find resources to learn more about the Tax Module and how to use it in your application.

Looking for no-code docs?: Refer to the Medusa Admin User Guide to learn how to manage tax regions using the dashboard.

Medusa has tax related features available out-of-the-box through the Tax Module. A module is a standalone package that provides features for a single domain. Each of Medusa's commerce features are placed in commerce modules, such as this Tax Module.

Note: Learn more about why modules are isolated in this documentation.

Tax Features#

Tax Settings Per Region: Set different tax settings for each tax region.
Tax Rates and Rules: Manage each region's default tax rates and override them with conditioned tax rates.
Retrieve Tax Lines for carts and orders: Calculate and retrieve the tax lines of a cart or order's line items and shipping methods with tax providers.

How to Use Tax Module's Service#

In your Medusa application, you build flows around commerce modules. A flow is built as a Workflow, which is a special function composed of a series of steps that guarantees data consistency and reliable roll-back mechanism.

You can build custom workflows and steps. You can also re-use Medusa's workflows and steps, which are provided by the @medusajs/medusa/core-flows package.

For example:

src/workflows/create-tax-region.ts
1import { 2  createWorkflow, 3  WorkflowResponse,4  createStep,5  StepResponse,6} from "@medusajs/framework/workflows-sdk"7import { Modules } from "@medusajs/framework/utils"8
9const createTaxRegionStep = createStep(10  "create-tax-region",11  async ({}, { container }) => {12    const taxModuleService = container.resolve(Modules.TAX)13
14    const taxRegion = await taxModuleService.createTaxRegions({15      country_code: "us",16    })17
18    return new StepResponse({ taxRegion }, taxRegion.id)19  },20  async (taxRegionId, { container }) => {21    if (!taxRegionId) {22      return23    }24    const taxModuleService = container.resolve(Modules.TAX)25
26    await taxModuleService.deleteTaxRegions([taxRegionId])27  }28)29
30export const createTaxRegionWorkflow = createWorkflow(31  "create-tax-region",32  () => {33    const { taxRegion } = createTaxRegionStep()34
35    return new WorkflowResponse({ taxRegion })36  }37)

You can then execute the workflow in your custom API routes, scheduled jobs, or subscribers:

Learn more about workflows in this documentation.

Configure Tax Module#

The Tax Module accepts options for further configurations. Refer to this documentation for details on the module's options.

Was this page helpful?