medusa-store/www/apps/resources/app/commerce-modules/tax/page.mdx

import { CodeTabs, CodeTab } from "docs-ui"

export const metadata = {
  title: `Tax Module`,
}

# {metadata.title}

The Tax Module is the `@medusajs/tax` NPM package that provides tax-related features in your Medusa and Node.js applications.

## Features

### Tax Settings Per Region

Set different tax settings for each tax region.

```ts
const taxRegion = await taxModuleService.createTaxRegions({
  country_code: "us",
})
```

### Tax Rates and Rules

Manage each region's default tax rates and override them with conditioned tax rates.

```ts
const taxRates = await taxModuleService.createTaxRates([
  {
    tax_region_id: "txreg_123",
    name: "Default tax rate",
    is_default: true,
    rate: 10,
  },
  {
    tax_region_id: "txreg_123",
    name: "Shirt product type",
    is_default: false,
    rate: 15,
    rules: [
      {
        reference: "product_type",
        reference_id: "ptyp_1",
      },
    ],
  },
])
```

### Retrieve Cart's Tax Lines

Calculate and retrieve the tax lines of a cart's line items and shipping methods with tax providers. Use different tax providers for each region to handle tax-line retrieval differently.

```ts
const taxLines = await taxModuleService.getTaxLines(
  [
    {
      id: "cali_123",
      product_id: "prod_123",
      unit_price: 1000,
      quantity: 1,
    },
    {
      id: "casm_123",
      shipping_option_id: "so_123",
      unit_price: 2000,
    },
  ],
  {
    address: {
      country_code: "us",
    },
  }
)
```

---

## Configure Tax Module

Refer to [this documentation](./module-options/page.mdx) for details on the module's options.

---

## How to Use Tax Module's Service

You can use the Tax Module's main service by resolving from the Medusa container the resource `ModuleRegistrationName.TAX` imported from `@medusajs/modules-sdk`.

For example:

<CodeTabs groupId="resource-type">
  <CodeTab label="API Route" value="api-route">

  ```ts title="src/api/store/custom/route.ts"
  import { MedusaRequest, MedusaResponse } from "@medusajs/medusa"
  import { ITaxModuleService } from "@medusajs/types"
  import { ModuleRegistrationName } from "@medusajs/utils"

export async function GET(
  req: MedusaRequest,
  res: MedusaResponse
): Promise<void> {
  const taxModuleService: ITaxModuleService = req.scope.resolve(
    ModuleRegistrationName.TAX
  )

  res.json({
    tax_regions: await taxModuleService.listTaxRegions(),
  })
}
```

  </CodeTab>
  <CodeTab label="Subscriber" value="subscribers">

  ```ts title="src/subscribers/custom-handler.ts"
  import { SubscriberArgs } from "@medusajs/medusa"
  import { ITaxModuleService } from "@medusajs/types"
  import { ModuleRegistrationName } from "@medusajs/utils"

export default async function subscriberHandler({ container }: SubscriberArgs) {
  const taxModuleService: ITaxModuleService = container.resolve(
    ModuleRegistrationName.TAX
  )

  const taxRegions = await taxModuleService.listTaxRegions()
}
```

  </CodeTab>
  <CodeTab label="Workflow Step" value="workflow-step">

  ```ts title="src/workflows/hello-world/step1.ts"
  import { createStep } from "@medusajs/workflows-sdk"
  import { ITaxModuleService } from "@medusajs/types"
  import { ModuleRegistrationName } from "@medusajs/utils"

const step1 = createStep("step-1", async (_, { container }) => {
  const taxModuleService: ITaxModuleService = container.resolve(
    ModuleRegistrationName.TAX
  )

  const taxRegions = await taxModuleService.listTaxRegions()
})
```

  </CodeTab>
</CodeTabs>