Skip to main content

How to Manage Tax Rates

In this document, you’ll learn how to manage tax rates of a region using the admin APIs.

Overview​

Tax rates are created per region. Each region has a default tax rate and code. However, you can create more tax rates for a region that have a different code or specific conditions. For example, you can override the default tax rate for a specific product type, product, or shipping option.

Scenario​

You want to add or use the following admin functionalities:

  • Manage tax rates. This includes listing tax rates, and creating, updating, and deleting a tax rate.
  • Add or delete a tax rate’s association with products, product types, or shipping options.

Prerequisites​

Medusa Components​

It is assumed that you already have a Medusa backend installed and set up. If not, you can follow the quickstart guide to get started.

JS Client​

This guide includes code snippets to send requests to your Medusa backend using Medusa’s JS Client, among other methods.

If you follow the JS Client code blocks, it’s assumed you already have Medusa’s JS Client installed and have created an instance of the client.

Medusa React​

This guide also includes code snippets to send requests to your Medusa backend using Medusa React, among other methods.

If you follow the Medusa React code blocks, it's assumed you already have Medusa React installed and have used MedusaProvider higher in your component tree.

Authenticated Admin User​

You must be an authenticated admin user before following along with the steps in the tutorial.

You can learn more about authenticating as an admin user in the API reference.

List Tax Rates​

You can list the tax rates by sending a request to the List Tax Rates endpoint:

medusa.admin.taxRates.list()
.then(({ tax_rates, limit, offset, count }) => {
  console.log(tax_rates.length)
})

You can pass to this endpoint filter and search parameters as explained in the API reference.

The endpoint returns an array of tax rate objects along with pagination parameters.

Listing Tax Rates for a Region​

You can retrieve the tax rate of a region by passing the region_id query parameter:

medusa.admin.taxRates.list({
  region_id: "reg_123",
})
.then(({ tax_rates, limit, offset, count }) => {
  console.log(tax_rates.length)
})

In the example above, you pass the region’s ID as the value of the region_id query parameter.

This query parameter also accepts an array of strings, allowing you to filter the tax rates by more than one region:

medusa.admin.taxRates.list({
  region_id: ["reg_123", "reg_456"],
})
.then(({ tax_rates, limit, offset, count }) => {
  console.log(tax_rates.length)
})

Create Tax Rate​

You can create a tax rate by sending a request to the Create Tax Rate endpoint:

medusa.admin.taxRates.create({
  code: "TEST",
  name: "New Tax Rate",
  region_id,
  rate: 10,
})
.then(({ tax_rate }) => {
  console.log(tax_rate.id)
})

This endpoint requires the following body parameters:

  • code: a string indicating the tax code
  • name: a string indicating the name of the tax rate
  • region_id: a string indicating the region this tax rate belongs to

You can optionally pass other parameters, such as rate, which is a number that indicates the tax rate. Refer to the API reference for other optional parameters.

You can specify here the products, product types, or shipping options that this tax rate is created for as explained in the API reference. In this guide, you’ll be using other endpoints to add or delete these conditions on a tax rate.

The request returns the created tax rate as an object.

Update Tax Rate​

You can update a tax rate by sending a request to the Update Tax Rate endpoint:

medusa.admin.taxRates.update(taxRateId, {
  name: "New Tax Rate",
})
.then(({ tax_rate }) => {
  console.log(tax_rate.id)
})

This endpoint requires the tax rate ID to be passed as a path parameter.

In the request body, you can pass any of the tax rate’s fields as a parameter. In the example above, you pass the name parameter to update the name of the tax rate. Refer to the API reference for other parameters you can pass in the request body.

The request returns the updated tax rate as an object.

Manage Tax Rate’s Products​

This section explains how you can add and remove products from a tax rate.

Add Product to Tax Rate​

You can add a product to a tax rate by sending a request to the Add Products endpoint:

medusa.admin.taxRates.addProducts(taxRateId, {
  products: [
    productId1,
  ],
})
.then(({ tax_rate }) => {
  console.log(tax_rate.products)
})

This endpoint requires the tax rate’s ID as a path parameter.

In the request body, the products parameter is required. It’s an array of strings, each string being the ID of a product to add to the tax rate.

The request returns the updated tax rate as an object. You can access the tax rate’s products using the products property of the tax rate object.

Remove Product from Tax Rate​

You can remove a product from a tax rate by sending a request to the Delete Products endpoint:

medusa.admin.taxRates.removeProducts(taxRateId, {
  products: [
    productId1,
  ],
})
.then(({ tax_rate }) => {
  console.log(tax_rate.products)
})

This endpoint requires the tax rate’s ID as a path parameter.

In the request body, the products parameter is required. It’s an array of strings, each string being the ID of a product to remove from the tax rate.

The request returns the updated tax rate as an object. You can access the tax rate’s products using the products property of the tax rate object.

Manage Tax Rate’s Product Types​

This section explains how you can add and remove product types from a tax rate.

Add Product Type to Tax Rate​

You can add a product type to a tax rate by sending a request to the Add Product Types endpoint:

medusa.admin.taxRates.addProductTypes(taxRateId, {
  product_types: [
    productTypeId,
  ],
})
.then(({ tax_rate }) => {
  console.log(tax_rate.product_types)
})

This endpoint requires the tax rate’s ID as a path parameter.

In the request body, the product_types parameter is required. It’s an array of strings, each string being the ID of a product type to add to the tax rate.

The request returns the updated tax rate as an object. You can access the tax rate’s product types using the product_types property of the tax rate object.

Remove Product Type from Tax Rate​

You can remove a product type from a tax rate by sending a request to the Delete Product Types endpoint:

medusa.admin.taxRates.removeProductTypes(taxRateId, {
  product_types: [
    productTypeId,
  ],
})
.then(({ tax_rate }) => {
  console.log(tax_rate.product_types)
})

This endpoint requires the tax rate’s ID as a path parameter.

In the request body, the product_types parameter is required. It’s an array of strings, each string being the ID of a product type to remove from the tax rate.

The request returns the updated tax rate as an object. You can access the tax rate’s product types using the product_types property of the tax rate object.

Manage Tax Rate’s Shipping Options​

This section explains how you can add and remove shipping options from a tax rate.

Add Shipping Option to Tax Rate​

You can add a shipping option to a tax rate by sending a request to the Add Shipping Option endpoint:

medusa.admin.taxRates.addShippingOptions(taxRateId, {
  shipping_options: [
    shippingOptionId,
  ],
})
.then(({ tax_rate }) => {
  console.log(tax_rate.shipping_options)
})

This endpoint requires the tax rate’s ID as a path parameter.

In the request body, the shipping_options parameter is required. It’s an array of strings, each string being the ID of a shipping option to add to the tax rate.

The request returns the updated tax rate as an object. You can access the tax rate’s shipping options using the shipping_options property of the tax rate object.

Remove Shipping Options from Tax Rate​

You can remove a shipping option from a tax rate by sending a request to the Delete Shipping Options endpoint:

medusa.admin.taxRates.removeShippingOptions(taxRateId, {
  shipping_options: [
    shippingOptionId,
  ],
})
.then(({ tax_rate }) => {
  console.log(tax_rate.shipping_options)
})

This endpoint requires the tax rate’s ID as a path parameter.

In the request body, the shipping_options parameter is required. It’s an array of strings, each string being the ID of a shipping option to remove from the tax rate.

The request returns the updated tax rate as an object. You can access the tax rate’s shipping options using the shipping_options property of the tax rate object.

Delete Tax Rate​

You can delete a tax rate by sending a request to the Delete Tax Rate endpoint:

medusa.admin.taxRates.delete(taxRateId)
.then(({ id, object, deleted }) => {
  console.log(id)
})

This endpoint requires the tax rate’s ID as a path parameter.

The request returns the following fields:

  • id: The ID of the deleted tax rate.
  • object: The type of object that was deleted. In this case, the value will be tax-rate.
  • deleted: A boolean value indicating whether the tax rate was deleted.

See Also​

Was this page helpful?
© 2023 Medusa, Inc. All rights reserved.