---
displayed_sidebar: homepage
---

import TypeList from "@site/src/components/TypeList"

# ITaxService

## Overview

A tax provider is used to retrieve the tax lines in a cart. The Medusa backend provides a default `system` provider. You can create your own tax provider,
either in a plugin or directly in your Medusa backend, then use it in any region.

A tax provider class is defined in a TypeScript or JavaScript file under the `src/services` directory and the class must extend the
`AbstractTaxService` class imported from `@medusajs/medusa`. The file's name is the tax provider's class name as a slug and without the word `Service`.

For example, you can create the file `src/services/my-tax.ts` with the following content:

```ts title="src/services/my-tax.ts"
import {
  AbstractTaxService,
  ItemTaxCalculationLine,
  ShippingTaxCalculationLine,
  TaxCalculationContext,
} from "@medusajs/medusa"
import {
  ProviderTaxLine,
} from "@medusajs/medusa/dist/types/tax-service"

class MyTaxService extends AbstractTaxService {
  async getTaxLines(
    itemLines: ItemTaxCalculationLine[],
    shippingLines: ShippingTaxCalculationLine[],
    context: TaxCalculationContext):
    Promise<ProviderTaxLine[]> {
    throw new Error("Method not implemented.")
  }
}

export default MyTaxService
```

---

## Identifier Property

The `TaxProvider` entity has 2 properties: `identifier` and `is_installed`. The `identifier` property in the tax provider service is used when the tax provider is added to the database.

The value of this property is also used to reference the tax provider throughout Medusa. For example, it is used to [change the tax provider](https://docs.medusajs.com/modules/taxes/admin/manage-tax-settings#change-tax-provider-of-a-region) to a region.

```ts title="src/services/my-tax.ts"
class MyTaxService extends AbstractTaxService {
  static identifier = "my-tax"
  // ...
}
```

---

## Methods

### getTaxLines

This method is used when retrieving the tax lines for line items and shipping methods.
This occurs during checkout or when calculating totals for orders, swaps, or returns.

#### Example

An example of how this method is implemented in the `system` provider implemented in the Medusa backend:

```ts
// ...

class SystemTaxService extends AbstractTaxService {
  // ...

  async getTaxLines(
    itemLines: ItemTaxCalculationLine[],
    shippingLines: ShippingTaxCalculationLine[],
    context: TaxCalculationContext
  ): Promise<ProviderTaxLine[]> {
    let taxLines: ProviderTaxLine[] = itemLines.flatMap((l) => {
      return l.rates.map((r) => ({
        rate: r.rate || 0,
        name: r.name,
        code: r.code,
        item_id: l.item.id,
      }))
    })

    taxLines = taxLines.concat(
      shippingLines.flatMap((l) => {
        return l.rates.map((r) => ({
          rate: r.rate || 0,
          name: r.name,
          code: r.code,
          shipping_method_id: l.shipping_method.id,
        }))
      })
    )

    return taxLines
  }
}
```

#### Parameters

<TypeList types={[{"name":"itemLines","type":"[ItemTaxCalculationLine](../types/medusa.ItemTaxCalculationLine.mdx)[]","description":"The line item lines to calculate taxes for.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"shippingLines","type":"[ShippingTaxCalculationLine](../types/medusa.ShippingTaxCalculationLine.mdx)[]","description":"The shipping method lines to calculate taxes for.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"context","type":"[TaxCalculationContext](../types/medusa.TaxCalculationContext.mdx)","description":"Context relevant and useful for the taxes calculation.","optional":false,"defaultValue":"","expandable":false,"children":[{"name":"shipping_address","type":"[Address](../../entities/classes/entities.Address.mdx) \\| `null`","description":"The shipping address used in the cart.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"customer","type":"[Customer](../../entities/classes/entities.Customer.mdx)","description":"The customer that the cart belongs to.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"region","type":"[Region](../../entities/classes/entities.Region.mdx)","description":"The cart's region.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"is_return","type":"`boolean`","description":"Whether the cart is used in a return flow.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"shipping_methods","type":"[ShippingMethod](../../entities/classes/entities.ShippingMethod.mdx)[]","description":"The shipping methods used in the cart.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"allocation_map","type":"[LineAllocationsMap](../types/medusa.LineAllocationsMap.mdx)","description":"The gift cards and discounts applied on line items.\nEach object key or property is an ID of a line item","optional":false,"defaultValue":"","expandable":false,"children":[]}]}]} expandUrl="https://docs.medusajs.com/development/entities/repositories#retrieving-a-list-of-records" sectionTitle="getTaxLines"/>

#### Returns

<TypeList types={[{"name":"Promise","type":"Promise&#60;[ProviderTaxLine](../types/medusa.ProviderTaxLine.mdx)[]&#62;","optional":false,"defaultValue":"","description":"The list of calculated line item and shipping method tax lines.\nIf an item in the array has the `shipping_method_id` property, then it's a shipping method tax line. Otherwise, if it has\nthe `item_id` property, then it's a line item tax line.","expandable":false,"children":[{"name":"ProviderTaxLine[]","type":"[ProviderTaxLine](../types/medusa.ProviderTaxLine.mdx)[]","optional":false,"defaultValue":"","description":"","expandable":false,"children":[]}]}]} expandUrl="https://docs.medusajs.com/development/entities/repositories#retrieving-a-list-of-records" sectionTitle="getTaxLines"/>