Skip to main content
Skip to main content
You're viewing the documentation for v1, which isn't the latest Medusa version.Latest documentation

TaxProviderService

Finds tax providers and assists in tax related operations.

constructor​

Parameters​

containerAwilixContainer<any>Required

Properties​

manager_EntityManagerRequired
transactionManager_undefined | EntityManagerRequired
__container__anyRequired
container_AwilixContainer<any>Required
cacheService_ICacheServiceRequired
taxRateService_TaxRateServiceRequired
taxLineRepo_Repository<LineItemTaxLine> & objectRequired
smTaxLineRepo_Repository<ShippingMethodTaxLine> & objectRequired
taxProviderRepo_Repository<TaxProvider>Required
eventBus_IEventBusServiceRequired
__configModule__Record<string, unknown>
__moduleDeclaration__Record<string, unknown>

Accessors​

activeManager_​

Returns​

EntityManagerEntityManagerRequired

Methods​

withTransaction​

Parameters​

transactionManagerEntityManager

Returns​

thisthisRequired

shouldRetryTransaction_​

Parameters​

errRecord<string, unknown> | objectRequired

Returns​

booleanbooleanRequired

atomicPhase_​

Wraps some work within a transactional block. If the service already has a transaction manager attached this will be reused, otherwise a new transaction manager is created.

Type Parameters​

TResultobjectRequired
TErrorobjectRequired

Parameters​

work(transactionManager: EntityManager) => Promise<TResult>Required
the transactional work to be done
isolationOrErrorHandlerIsolationLevel | (error: TError) => Promise<void | TResult>
the isolation level to be used for the work.
maybeErrorHandlerOrDontFail(error: TError) => Promise<void | TResult>
Potential error handler

Returns​

PromisePromise<TResult>Required
the result of the transactional work

list​

Returns​

PromisePromise<TaxProvider[]>Required

retrieveProvider​

Retrieves the relevant tax provider for the given region.

Parameters​

regionRegionRequired
the region to get tax provider for.

Returns​

ITaxServiceobjectRequired
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: 
1import {2  AbstractTaxService,3  ItemTaxCalculationLine,4  ShippingTaxCalculationLine,5  TaxCalculationContext,6} from "@medusajs/medusa"7import {8  ProviderTaxLine,9} from "@medusajs/medusa/dist/types/tax-service"10
11class MyTaxService extends AbstractTaxService {12  async getTaxLines(13    itemLines: ItemTaxCalculationLine[],14    shippingLines: ShippingTaxCalculationLine[],15    context: TaxCalculationContext):16    Promise<ProviderTaxLine[]> {17    throw new Error("Method not implemented.")18  }19}20
21export 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 to a region. 
1class MyTaxService extends AbstractTaxService {2  static identifier = "my-tax"3  // ...4}

clearLineItemsTaxLines​

Parameters​

itemIdsstring[]Required

Returns​

PromisePromise<void>Required

clearTaxLines​

Parameters​

cartIdstringRequired

Returns​

PromisePromise<void>Required

createTaxLines​

Persists the tax lines relevant for an order to the database.

Parameters​

cartOrLineItemsCart | LineItem[]Required
the cart or line items to create tax lines for
calculationContextTaxCalculationContextRequired
the calculation context to get tax lines by

Returns​

PromisePromise<(ShippingMethodTaxLine | LineItemTaxLine)[]>Required
the newly created tax lines

createShippingTaxLines​

Persists the tax lines relevant for a shipping method to the database. Used for return shipping methods.

Parameters​

shippingMethodShippingMethodRequired
the shipping method to create tax lines for
calculationContextTaxCalculationContextRequired
the calculation context to get tax lines by

Returns​

PromisePromise<(ShippingMethodTaxLine | LineItemTaxLine)[]>Required
the newly created tax lines

getShippingTaxLines​

Gets the relevant tax lines for a shipping method. Note: this method doesn't persist the tax lines. Use createShippingTaxLines if you wish to persist the tax lines to the DB layer.

Parameters​

shippingMethodShippingMethodRequired
the shipping method to get tax lines for
calculationContextTaxCalculationContextRequired
the calculation context to get tax lines by

Returns​

PromisePromise<ShippingMethodTaxLine[]>Required
the computed tax lines

getTaxLines​

Gets the relevant tax lines for an order or cart. If an order is provided the order's tax lines will be returned. If a cart is provided the tax lines will be computed from the tax rules and potentially a 3rd party tax plugin. Note: this method doesn't persist the tax lines. Use createTaxLines if you wish to persist the tax lines to the DB layer.

Parameters​

lineItemsLineItem[]Required
the cart or order to get tax lines for
calculationContextTaxCalculationContextRequired
the calculation context to get tax lines by

Returns​

PromisePromise<(ShippingMethodTaxLine | LineItemTaxLine)[]>Required
the computed tax lines

getTaxLinesMap​

Return a map of tax lines for line items and shipping methods

Parameters​

itemsLineItem[]Required
calculationContextTaxCalculationContextRequired

Returns​

PromisePromise<TaxLinesMaps>Required
Return a map of tax lines for line items and shipping methods

getRegionRatesForShipping​

Gets the tax rates configured for a shipping option. The rates are cached between calls.

Parameters​

optionIdstringRequired
the option id of the shipping method.
regionDetailsRegionDetailsRequired
the region to get configured rates for.

Returns​

PromisePromise<TaxServiceRate[]>Required
the tax rates configured for the shipping option.

getRegionRatesForProduct​

Gets the tax rates configured for a product. The rates are cached between calls.

Parameters​

productIdsstring | string[]Required
regionRegionDetailsRequired
the region to get configured rates for.

Returns​

PromisePromise<Map<string, TaxServiceRate[]>>Required
the tax rates configured for the shipping option. A map by product id

getCacheKey​

The cache key to get cache hits by.

Parameters​

idstringRequired
the entity id to cache
regionIdstringRequired
the region id to cache

Returns​

stringstringRequired
the cache key to use for the id set

registerInstalledProviders​

Parameters​

providersstring[]Required

Returns​

PromisePromise<void>Required
Was this section helpful?
© 2026 Medusa, Inc. All rights reserved.