How to Create a Tax Provider

In this document, you’ll learn how to create a tax provider to use with the Tax Module, and the methods to implement.

Overview

A tax provider is used to retrieve the tax lines in a provided context. The Tax Module provides a default system provider. You can create your own tax provider, either in a plugin, in a provider module, or directly in your Medusa application's codebase, then use it in any tax region.

---

How to Create a Tax Provider

A tax provider class is defined in a TypeScript or JavaScript file. The class must implement the ITaxProvider interface imported from @medusajs/types.

The file can be defined in a plugin, a provider module, or under the src/services directory of your Medusa application. You can later pass the package's name or the path to the file in the providers option of the Tax Module.

For example:

src/services/my-tax.ts

import { ITaxProvider } from "@medusajs/types"

export default class MyTaxProvider implements ITaxProvider {
  // ...
}

---

Identifier Property

The identifier property in a tax provider is used when the tax provider is registered in the dependency container or added to the database. A tax provider is represented in the database by the TaxProvider data model.

For example:

src/services/my-tax.ts

export default class MyTaxProvider implements ITaxProvider {
  static identifier = "my-tax"
  // ...
}

---

Constructor

You can use the constructor of your tax provider to access the resources registered in the dependency container.

You can also use the constructor to initialize your integration with the third-party provider. For example, if you use a client to connect to the third-party provider’s APIs, you can initialize it in the constructor and use it in other methods in the service.

Additionally, if you’re creating your tax provider as a plugin or a provider module to be installed in any Medusa application and you want to access its options, you can access them in the constructor.

For example:

export default class MyTaxProvider implements ITaxProvider {
  // ...
  constructor(container, options) {
    // you can access options here

    // you can also initialize a client that
    // communicates with a third-party service.
    this.client = new Client(options)
  }
}

---

getTaxLines

This method is used to retrieve the tax lines of items and shipping methods. It's used when the getTaxLines method of the Tax Module's main service is called.

This method is useful during checkout or when calculating the totals of orders or exchanges.

Example

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

// ...

export default class SystemTaxService implements ITaxProvider {
  // ...

  async getTaxLines(
    itemLines: TaxTypes.ItemTaxCalculationLine[],
    shippingLines: TaxTypes.ShippingTaxCalculationLine[],
    _: TaxTypes.TaxCalculationContext
  ): Promise<(TaxTypes.ItemTaxLineDTO | TaxTypes.ShippingTaxLineDTO)[]> {
    let taxLines: (TaxTypes.ItemTaxLineDTO | TaxTypes.ShippingTaxLineDTO)[] =
      itemLines.flatMap((l) => {
        return l.rates.map((r) => ({
          rate_id: r.id,
          rate: r.rate || 0,
          name: r.name,
          code: r.code,
          line_item_id: l.line_item.id,
          provider_id: this.getIdentifier(),
        }))
      })

    taxLines = taxLines.concat(
      shippingLines.flatMap((l) => {
        return l.rates.map((r) => ({
          rate_id: r.id,
          rate: r.rate || 0,
          name: r.name,
          code: r.code,
          shipping_line_id: l.shipping_line.id,
          provider_id: this.getIdentifier(),
        }))
      })
    )

    return taxLines
  }
}

Parameters

itemLinesItemTaxCalculationLine[]Required

The line item lines to calculate taxes for.

shippingLinesShippingTaxCalculationLine[]Required

The shipping method lines to calculate taxes for.

contextTaxCalculationContextRequired

The context relevant and useful for the taxes calculation.

Returns

PromisePromise<(ItemTaxLineDTO | ShippingTaxLineDTO)[]>Required

The list of calculated line item and shipping tax lines. If an item in the array has the shipping_line_id property, then it's a shipping tax line. Otherwise, if it has the line_item_id property, then it's a line item tax line.