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

ITaxModuleService

The main service interface for the Tax Module.

Methods​

retrieve​

This method retrieves a tax by its ID.

Example​

A simple example that retrieves a tax rate by its ID:

const taxRate = await taxModuleService.retrieve("txr_123")

To specify relations that should be retrieved:

const taxRate = await taxModuleService.retrieve("txr_123", {
  relations: ["tax_region"],
})

Parameters​

taxRateIdstringRequired
The tax rate's ID.
configFindConfig<TaxRateDTO>
The configurations determining how the tax rate is retrieved. Its properties, such as select or relations, accept the attributes or relations associated with a tax rate.
sharedContextContext
A context used to share resources, such as transaction manager, between the application and the module.

Returns​

PromisePromise<TaxRateDTO>Required
The retrieved tax.

list​

This method retrieves a paginated list of tax rates based on optional filters and configuration.

Example​

To retrieve a list of tax rates using their IDs:

const taxRates = await taxModuleService.list({
  id: ["txr_123", "txr_321"],
})

To specify relations that should be retrieved within the tax rate:

const taxRates = await taxModuleService.list(
  {
    id: ["txr_123", "txr_321"],
  },
  {
    relations: ["tax_region"],
  }
)

By default, only the first 15 records are retrieved. You can control pagination by specifying the skip and take properties of the config parameter:

const taxRates = await taxModuleService.list(
  {
    id: ["txr_123", "txr_321"],
  },
  {
    relations: ["tax_region"],
    take: 20,
    skip: 2,
  }
)

Parameters​

filtersFilterableTaxRateProps
The filters to apply on the retrieved tax rates.
configFindConfig<TaxRateDTO>
The configurations determining how the tax rate is retrieved. Its properties, such as select or relations, accept the attributes or relations associated with a tax rate.
sharedContextContext
A context used to share resources, such as transaction manager, between the application and the module.

Returns​

PromisePromise<TaxRateDTO[]>Required
The list of tax rates.

listAndCount​

This method retrieves a paginated list of tax rates along with the total count of available tax rates satisfying the provided filters.

Example​

To retrieve a list of tax rates using their IDs:

const [taxRates, count] = await taxModuleService.listAndCount(
  {
    id: ["txr_123", "txr_321"],
  }
)

To specify relations that should be retrieved within the tax rate:

const [taxRates, count] = await taxModuleService.listAndCount(
  {
    id: ["txr_123", "txr_321"],
  },
  {
    relations: ["tax_region"],
  }
)

By default, only the first 15 records are retrieved. You can control pagination by specifying the skip and take properties of the config parameter:

const [taxRates, count] = await taxModuleService.listAndCount(
  {
    id: ["txr_123", "txr_321"],
  },
  {
    relations: ["tax_region"],
    take: 20,
    skip: 2,
  }
)

Parameters​

filtersFilterableTaxRateProps
The filters to apply on the retrieved tax rates.
configFindConfig<TaxRateDTO>
The configurations determining how the tax rate is retrieved. Its properties, such as select or relations, accept the attributes or relations associated with a tax rate.
sharedContextContext
A context used to share resources, such as transaction manager, between the application and the module.

Returns​

PromisePromise<[TaxRateDTO[], number]>Required
The list of tax rates along with their total count.

create​

**create**(data, sharedContext?): Promise&#60;[TaxRateDTO](types.TaxTypes.TaxRateDTO.mdx)[]&#62;

This method creates tax rates.

Example​

const taxRates = await taxModuleService.create([
  {
    tax_region_id: "txreg_123",
    name: "Default rate",
    rate: 10,
  },
  {
    tax_region_id: "txreg_123",
    name: "Custom rate",
    rate: 15,
    rules: [
      {
        reference: "product_type",
        reference_id: "ptyp_1",
      },
      {
        reference: "product",
        reference_id: "prod_123",
      },
    ],
  },
])

Parameters​

dataCreateTaxRateDTO[]Required
The tax rates to be created.
sharedContextContext
A context used to share resources, such as transaction manager, between the application and the module.

Returns​

PromisePromise<TaxRateDTO[]>Required
The created tax rates.

**create**(data, sharedContext?): Promise&#60;[TaxRateDTO](types.TaxTypes.TaxRateDTO.mdx)&#62;

This method creates a tax rate.

Example​

const taxRate = await taxModuleService.create({
  tax_region_id: "txreg_123",
  name: "Default rate",
  rate: 10,
})

Parameters​

dataCreateTaxRateDTORequired
The tax rate to be created.
sharedContextContext
A context used to share resources, such as transaction manager, between the application and the module.

Returns​

PromisePromise<TaxRateDTO>Required
The created tax rate.

update​

**update**(taxRateId, data, sharedContext?): Promise&#60;[TaxRateDTO](types.TaxTypes.TaxRateDTO.mdx)&#62;

This method updates an existing tax rate.

Example​

const taxRate = await taxModuleService.update("txr_123", {
  rate: 10,
})

Parameters​

taxRateIdstringRequired
The tax rate's ID.
dataUpdateTaxRateDTORequired
The attributes to update in the tax rate.
sharedContextContext
A context used to share resources, such as transaction manager, between the application and the module.

Returns​

PromisePromise<TaxRateDTO>Required
The updated tax rate.

**update**(taxRateIds, data, sharedContext?): Promise&#60;[TaxRateDTO](types.TaxTypes.TaxRateDTO.mdx)[]&#62;

This method updates existing tax rates.

Example​

const taxRates = await taxModuleService.update(
  ["txr_123", "txr_321"],
  {
    rate: 10,
  }
)

Parameters​

taxRateIdsstring[]Required
The IDs of tax rates to update.
dataUpdateTaxRateDTORequired
The attributes to update in the tax rate.
sharedContextContext
A context used to share resources, such as transaction manager, between the application and the module.

Returns​

PromisePromise<TaxRateDTO[]>Required
The updated tax rates.

**update**(selector, data, sharedContext?): Promise&#60;[TaxRateDTO](types.TaxTypes.TaxRateDTO.mdx)[]&#62;

This method updates existing tax rates matching the specified filters.

Example​

const taxRates = await taxModuleService.update(
  {
    id: ["txr_123", "txr_321"],
  },
  {
    rate: 10,
  }
)

Parameters​

selectorFilterableTaxRatePropsRequired
The filters specifying which tax rates to update.
dataUpdateTaxRateDTORequired
The attributes to update in the tax rate.
sharedContextContext
A context used to share resources, such as transaction manager, between the application and the module.

Returns​

PromisePromise<TaxRateDTO[]>Required
The updated tax rates.

upsert​

**upsert**(data, sharedContext?): Promise&#60;[TaxRateDTO](types.TaxTypes.TaxRateDTO.mdx)&#62;

This method updates or creates a tax rate if it doesn't exist.

Example​

const taxRate = await taxModuleService.upsert({
  id: "txr_123",
  rate: 10,
})

Parameters​

dataUpsertTaxRateDTORequired
The attributes in the tax rate to be created or updated.
sharedContextContext
A context used to share resources, such as transaction manager, between the application and the module.

Returns​

PromisePromise<TaxRateDTO>Required
The created or updated tax rate.

**upsert**(data, sharedContext?): Promise&#60;[TaxRateDTO](types.TaxTypes.TaxRateDTO.mdx)[]&#62;

This method updates or creates tax rates if they don't exist.

Example​

const taxRates = await taxModuleService.upsert([
  {
    id: "txr_123",
    rate: 10,
  },
])

Parameters​

dataUpsertTaxRateDTO[]Required
The attributes in the tax rates to be created or updated.
sharedContextContext
A context used to share resources, such as transaction manager, between the application and the module.

Returns​

PromisePromise<TaxRateDTO[]>Required
The created or updated tax rates.

delete​

**delete**(taxRateIds, sharedContext?): Promise&#60;void&#62;

This method deletes tax rates by their IDs.

Example​

await taxModuleService.delete(["txr_123", "txr_321"])

Parameters​

taxRateIdsstring[]Required
The IDs of tax rates to delete.
sharedContextContext
A context used to share resources, such as transaction manager, between the application and the module.

Returns​

PromisePromise<void>Required
Resolves when the tax rates are deleted successfully.

**delete**(taxRateId, sharedContext?): Promise&#60;void&#62;

This method deletes a tax rate by its ID.

Example​

await taxModuleService.delete("txr_123")

Parameters​

taxRateIdstringRequired
The tax rate's ID.
sharedContextContext
A context used to share resources, such as transaction manager, between the application and the module.

Returns​

PromisePromise<void>Required
Resolves when the tax rate is deleted successfully.

restore​

This method restores soft deleted tax rates by their IDs.

Example​

await taxModuleService.restore(["txr_123", "txr_321"])

Type Parameters​

TReturnableLinkableKeysstringRequired

Parameters​

taxRateIdsstring[]Required
The IDs of the tax rates.
configRestoreReturn<TReturnableLinkableKeys>
Configurations determining which relations to restore along with each of the tax. You can pass to its returnLinkableKeys property any of the tax rate's relation attribute names, such as rules.
sharedContextContext
A context used to share resources, such as transaction manager, between the application and the module.

Returns​

PromisePromise<void | Record<string, string[]>>Required
An object that includes the IDs of related records that were restored, such as the ID of associated rules. The object's keys are the ID attribute names of the tax rate entity's relations, such as rule_id, and its value is an array of strings, each being the ID of the record associated with the tax rate through this relation, such as the IDs of associated rules. If there are no related records restored, the promise resolves to void.

createTaxRegions​

**createTaxRegions**(data, sharedContext?): Promise&#60;[TaxRegionDTO](types.TaxTypes.TaxRegionDTO.mdx)&#62;

This method creates a tax region.

Example​

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

Parameters​

dataCreateTaxRegionDTORequired
The tax region to be created.
sharedContextContext
A context used to share resources, such as transaction manager, between the application and the module.

Returns​

PromisePromise<TaxRegionDTO>Required
The created tax region.

**createTaxRegions**(data, sharedContext?): Promise&#60;[TaxRegionDTO](types.TaxTypes.TaxRegionDTO.mdx)[]&#62;

This method creates tax regions.

Example​

const taxRegions = await taxModuleService.createTaxRegions([
  {
    country_code: "us",
  },
  {
    country_code: "gb",
  },
])

Parameters​

dataCreateTaxRegionDTO[]Required
The tax regions to be created.
sharedContextContext
A context used to share resources, such as transaction manager, between the application and the module.

Returns​

PromisePromise<TaxRegionDTO[]>Required
The created tax regions.

deleteTaxRegions​

**deleteTaxRegions**(taxRegionIds, sharedContext?): Promise&#60;void&#62;

This method deletes tax regions by their IDs.

Example​

await taxModuleService.deleteTaxRegions([
  "txreg_123",
  "txreg_321",
])

Parameters​

taxRegionIdsstring[]Required
The IDs of the tax regions.
sharedContextContext
A context used to share resources, such as transaction manager, between the application and the module.

Returns​

PromisePromise<void>Required
Resolves when the tax regions are deleted.

**deleteTaxRegions**(taxRegionId, sharedContext?): Promise&#60;void&#62;

This method deletes a tax region by its ID.

Example​

await taxModuleService.deleteTaxRegions("txreg_123")

Parameters​

taxRegionIdstringRequired
The tax region's ID.
sharedContextContext
A context used to share resources, such as transaction manager, between the application and the module.

Returns​

PromisePromise<void>Required
Resolves when the tax region is successfully deleted.

listTaxRegions​

This method retrieves a paginated list of tax regions based on optional filters and configuration.

Example​

To retrieve a list of tax regions using their IDs:

const taxRegions = await taxModuleService.listTaxRegions({
  id: ["txreg_123", "txreg_321"],
})

To specify relations that should be retrieved within the tax region:

const taxRegions = await taxModuleService.listTaxRegions(
  {
    id: ["txreg_123", "txreg_321"],
  },
  {
    relations: ["tax_rates"],
  }
)

By default, only the first 15 records are retrieved. You can control pagination by specifying the skip and take properties of the config parameter:

const taxRegions = await taxModuleService.listTaxRegions(
  {
    id: ["txreg_123", "txreg_321"],
  },
  {
    relations: ["tax_rates"],
    take: 20,
    skip: 2,
  }
)

Parameters​

filtersFilterableTaxRegionProps
The filters to apply on the retrieved tax regions.
configFindConfig<TaxRegionDTO>
The configurations determining how the tax region is retrieved. Its properties, such as select or relations, accept the attributes or relations associated with a tax region.
sharedContextContext
A context used to share resources, such as transaction manager, between the application and the module.

Returns​

PromisePromise<TaxRegionDTO[]>Required
The list of tax regions.

createTaxRateRules​

**createTaxRateRules**(data, sharedContext?): Promise&#60;[TaxRateRuleDTO](types.TaxTypes.TaxRateRuleDTO.mdx)&#62;

This method creates a tax rate rule.

Example​

const taxRateRule = await taxModuleService.createTaxRateRules(
  {
    reference: "product_type",
    reference_id: "ptyp_123",
    tax_rate_id: "txr_123",
  }
)

Parameters​

dataCreateTaxRateRuleDTORequired
The tax rate rule to be created.
sharedContextContext
A context used to share resources, such as transaction manager, between the application and the module.

Returns​

PromisePromise<TaxRateRuleDTO>Required
The created tax rate rule.

**createTaxRateRules**(data, sharedContext?): Promise&#60;[TaxRateRuleDTO](types.TaxTypes.TaxRateRuleDTO.mdx)[]&#62;

This method creates tax rate rules.

Example​

const taxRateRules =
  await taxModuleService.createTaxRateRules([
    {
      reference: "product_type",
      reference_id: "ptyp_123",
      tax_rate_id: "txr_123",
    },
    {
      reference: "product",
      reference_id: "prod_123",
      tax_rate_id: "txr_321",
    },
  ])

Parameters​

dataCreateTaxRateRuleDTO[]Required
The tax rate rules to be created.
sharedContextContext
A context used to share resources, such as transaction manager, between the application and the module.

Returns​

PromisePromise<TaxRateRuleDTO[]>Required
The created tax rate rules.

deleteTaxRateRules​

**deleteTaxRateRules**(taxRateRuleId, sharedContext?): Promise&#60;void&#62;

This method deletes a tax rate rule by its ID.

Example​

await taxModuleService.deleteTaxRateRules("txrule_123")

Parameters​

taxRateRuleIdstringRequired
The tax rate rule's ID.
sharedContextContext
A context used to share resources, such as transaction manager, between the application and the module.

Returns​

PromisePromise<void>Required
Resolves when the tax rate rule is deleted successfully.

**deleteTaxRateRules**(taxRateRuleIds, sharedContext?): Promise&#60;void&#62;

This method deletes tax rate rules by their IDs.

Example​

await taxModuleService.deleteTaxRateRules([
  "txrule_123",
  "txrule_321",
])

Parameters​

taxRateRuleIdsstring[]Required
The tax rate rules' IDs.
sharedContextContext
A context used to share resources, such as transaction manager, between the application and the module.

Returns​

PromisePromise<void>Required
Resolves when the tax rate rules are deleted successfully.

listTaxRateRules​

This method retrieves a paginated list of tax rate rules based on optional filters and configuration.

Example​

To retrieve a list of tax rate rules using their associated tax rate's ID:

const taxRateRules = await taxModuleService.listTaxRateRules({
  tax_rate_id: ["txr_123", "txr_321"],
})

To specify relations that should be retrieved within the tax rate rule:

const taxRateRules = await taxModuleService.listTaxRateRules(
  {
    tax_rate_id: ["txr_123", "txr_321"],
  },
  {
    relations: ["tax_rate"],
  }
)

By default, only the first 15 records are retrieved. You can control pagination by specifying the skip and take properties of the config parameter:

const taxRateRules = await taxModuleService.listTaxRateRules(
  {
    tax_rate_id: ["txr_123", "txr_321"],
  },
  {
    relations: ["tax_rate"],
    take: 20,
    skip: 2,
  }
)

Parameters​

filtersFilterableTaxRateRuleProps
The filters to apply on the retrieved tax rate rules.
configFindConfig<TaxRateRuleDTO>
The configurations determining how the tax rate rule is retrieved. Its properties, such as select or relations, accept the attributes or relations associated with a tax rate rule.
sharedContextContext
A context used to share resources, such as transaction manager, between the application and the module.

Returns​

PromisePromise<TaxRateRuleDTO[]>Required
The list of tax rate rules.

getTaxLines​

This method retrieves tax lines for taxable items and shipping methods in a cart.

Learn more in this guide.

Example​

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",
    },
  }
)

Parameters​

items(TaxableItemDTO | TaxableShippingDTO)[]Required
The items and shipping methods to retrieve their tax lines.
calculationContextTaxCalculationContextRequired
The context to pass to the underlying tax provider. It provides more details that are useful to provide accurate tax lines.
sharedContextContext
A context used to share resources, such as transaction manager, between the application and the module.

Returns​

PromisePromise<(ItemTaxLineDTO | ShippingTaxLineDTO)[]>Required
The item and shipping methods' tax lines.

softDelete​

This method soft deletes tax raes by their IDs.

Example​

await taxModuleService.softDelete(["txr_123", "txr_321"])

Type Parameters​

TReturnableLinkableKeysstringRequired

Parameters​

taxRateIdsstring[]Required
The IDs of the tax rates.
configSoftDeleteReturn<TReturnableLinkableKeys>
An object that is used to specify an entity's related entities that should be soft-deleted when the main entity is soft-deleted.
sharedContextContext
A context used to share resources, such as transaction manager, between the application and the module.

Returns​

PromisePromise<void | Record<string, string[]>>Required
An object that includes the IDs of related records that were also soft deleted, such as the ID of the associated rules. The object's keys are the ID attribute names of the tax rate entity's relations, such as rule_id, and its value is an array of strings, each being the ID of a record associated with the tax rate through this relation, such as the IDs of associated rules. If there are no related records, the promise resolves to void.

softDeleteTaxRegions​

This method soft deletes tax regions by their IDs.

Example​

await taxModuleService.softDeleteTaxRegions([
  "txreg_123",
  "txreg_321",
])

Type Parameters​

TReturnableLinkableKeysstringRequired

Parameters​

taxRegionIdsstring[]Required
The IDs of the tax regions.
configSoftDeleteReturn<TReturnableLinkableKeys>
An object that is used to specify an entity's related entities that should be soft-deleted when the main entity is soft-deleted.
sharedContextContext
A context used to share resources, such as transaction manager, between the application and the module.

Returns​

PromisePromise<void | Record<string, string[]>>Required
An object that includes the IDs of related records that were also soft deleted, such as the ID of the associated tax rates. The object's keys are the ID attribute names of the tax region entity's relations, such as tax_rate_id, and its value is an array of strings, each being the ID of a record associated with the tax region through this relation, such as the IDs of associated tax rates. If there are no related records, the promise resolves to void.

restoreTaxRegions​

This method restores soft deleted tax regions by their IDs.

Example​

await taxModuleService.restoreTaxRegions([
  "txreg_123",
  "txreg_321",
])

Type Parameters​

TReturnableLinkableKeysstringRequired

Parameters​

taxRegionIdsstring[]Required
The IDs of the tax regions.
configRestoreReturn<TReturnableLinkableKeys>
Configurations determining which relations to restore along with each of the tax. You can pass to its returnLinkableKeys property any of the tax region's relation attribute names, such as tax_rates.
sharedContextContext
A context used to share resources, such as transaction manager, between the application and the module.

Returns​

PromisePromise<void | Record<string, string[]>>Required
An object that includes the IDs of related records that were restored, such as the ID of associated tax rates. The object's keys are the ID attribute names of the tax region entity's relations, such as tax_rate_id, and its value is an array of strings, each being the ID of the record associated with the tax region through this relation, such as the IDs of associated tax rates. If there are no related records restored, the promise resolves to void.

softDeleteTaxRateRules​

This method soft deletes tax rate rules by their IDs.

Example​

await taxModuleService.softDeleteTaxRateRules([
  "txrule_123",
  "txrule_321",
])

Type Parameters​

TReturnableLinkableKeysstringRequired

Parameters​

taxRateRuleIdsstring[]Required
The IDs of the tax rate rules.
configSoftDeleteReturn<TReturnableLinkableKeys>
An object that is used to specify an entity's related entities that should be soft-deleted when the main entity is soft-deleted.
sharedContextContext
A context used to share resources, such as transaction manager, between the application and the module.

Returns​

PromisePromise<void | Record<string, string[]>>Required
An object that includes the IDs of related records that were also soft deleted. If there are no related records, the promise resolves to void.

restoreTaxRateRules​

This method restores soft deleted tax rate rules by their IDs.

Example​

await taxModuleService.restoreTaxRateRules([
  "txrule_123",
  "txrule_321",
])

Type Parameters​

TReturnableLinkableKeysstringRequired

Parameters​

taxRateRuleIdsstring[]Required
The IDs of the tax rate rules.
configRestoreReturn<TReturnableLinkableKeys>
Configurations determining which relations to restore along with each of the tax. You can pass to its returnLinkableKeys property any of the tax rate rule's relation attribute names.
sharedContextContext
A context used to share resources, such as transaction manager, between the application and the module.

Returns​

PromisePromise<void | Record<string, string[]>>Required
An object that includes the IDs of related records that were restored. If there are no related records restored, the promise resolves to void.
Was this section helpful?
© 2025 Medusa, Inc. All rights reserved.