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/framework/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
1import { ITaxProvider } from "@medusajs/framework/types"2
3export default class MyTaxProvider implements ITaxProvider {4  // ...5}

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
1export default class MyTaxProvider implements ITaxProvider {2  static identifier = "my-tax"3  // ...4}

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:

Code
1export default class MyTaxProvider implements ITaxProvider {2  // ...3  constructor(container, options) {4    // you can access options here5
6    // you can also initialize a client that7    // communicates with a third-party service.8    this.client = new Client(options)9  }10}

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:

Code
1// ...2
3export default class SystemTaxService implements ITaxProvider {4  // ...5
6  async getTaxLines(7    itemLines: TaxTypes.ItemTaxCalculationLine[],8    shippingLines: TaxTypes.ShippingTaxCalculationLine[],9    _: TaxTypes.TaxCalculationContext10  ): Promise<(TaxTypes.ItemTaxLineDTO | TaxTypes.ShippingTaxLineDTO)[]> {11    let taxLines: (TaxTypes.ItemTaxLineDTO | TaxTypes.ShippingTaxLineDTO)[] =12      itemLines.flatMap((l) => {13        return l.rates.map((r) => ({14          rate_id: r.id,15          rate: r.rate || 0,16          name: r.name,17          code: r.code,18          line_item_id: l.line_item.id,19          provider_id: this.getIdentifier(),20        }))21      })22
23    taxLines = taxLines.concat(24      shippingLines.flatMap((l) => {25        return l.rates.map((r) => ({26          rate_id: r.id,27          rate: r.rate || 0,28          name: r.name,29          code: r.code,30          shipping_line_id: l.shipping_line.id,31          provider_id: this.getIdentifier(),32        }))33      })34    )35
36    return taxLines37  }38}

Parameters#

Returns#