AdminTaxRatesResource

This class is used to send requests to Admin Tax Rate API Routes. All its method are available in the JS Client under the medusa.admin.taxRates property.

All methods in this class require user authentication.

Each region has at least a default tax rate. Admins can create and manage additional tax rates that can be applied for certain conditions, such as for specific product types.

Related Guide: How to manage tax rates.

Methods

addProductTypes

Add product types to a tax rate.

Example

import Medusa from "@medusajs/medusa-js"
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
// must be previously logged in or use api token
medusa.admin.taxRates.addProductTypes(taxRateId, {
  product_types: [
    productTypeId
  ]
})
.then(({ tax_rate }) => {
  console.log(tax_rate.id);
})

Parameters

idstringRequired

The tax rate's ID.

payloadAdminPostTaxRatesTaxRateProductTypesReqRequired

The product types to add to the tax rate.

queryAdminGetTaxRatesTaxRateParams

Configurations to apply on the retrieved tax rate.

customHeadersRecord<string, any>Required

Custom headers to attach to the request.

Default: {}

Returns

ResponsePromiseResponsePromise<AdminTaxRatesRes>Required

Resolves to the tax rate's details.

---

addProducts

Add products to a tax rate.

Example

import Medusa from "@medusajs/medusa-js"
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
// must be previously logged in or use api token
medusa.admin.taxRates.addProducts(taxRateId, {
  products: [
    productId
  ]
})
.then(({ tax_rate }) => {
  console.log(tax_rate.id);
})

Parameters

idstringRequired

The tax rate's ID.

payloadAdminPostTaxRatesTaxRateProductsReqRequired

The products to add to the tax rate.

queryAdminPostTaxRatesTaxRateProductsParams

Configurations to apply on the retrieved tax rate.

customHeadersRecord<string, any>Required

Custom headers to attach to the request.

Default: {}

Returns

ResponsePromiseResponsePromise<AdminTaxRatesRes>Required

Resolves to the tax rate's details.

---

addShippingOptions

Add shipping options to a tax rate.

Example

import Medusa from "@medusajs/medusa-js"
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
// must be previously logged in or use api token
medusa.admin.taxRates.addShippingOptions(taxRateId, {
  shipping_options: [
    shippingOptionId
  ]
})
.then(({ tax_rate }) => {
  console.log(tax_rate.id);
})

Parameters

idstringRequired

The tax rate's ID.

payloadAdminPostTaxRatesTaxRateShippingOptionsReqRequired

The shipping options to add to the tax rate.

queryAdminPostTaxRatesTaxRateShippingOptionsParams

Configurations to apply on the retrieved tax rate.

customHeadersRecord<string, any>Required

Custom headers to attach to the request.

Default: {}

Returns

ResponsePromiseResponsePromise<AdminTaxRatesRes>Required

Resolves to the tax rate's details.

---

create

Create a tax rate.

Example

import Medusa from "@medusajs/medusa-js"
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
// must be previously logged in or use api token
medusa.admin.taxRates.create({
  code: "TEST",
  name: "New Tax Rate",
  region_id
})
.then(({ tax_rate }) => {
  console.log(tax_rate.id);
})

Parameters

payloadAdminPostTaxRatesReqRequired

The tax rate to create.

queryAdminPostTaxRatesParams

Configurations to apply on the retrieved tax rate.

customHeadersRecord<string, any>Required

Custom headers to attach to the request.

Default: {}

Returns

ResponsePromiseResponsePromise<AdminTaxRatesRes>Required

Resolves to the tax rate's details.

---

delete

Delete a tax rate. Resources associated with the tax rate, such as products or product types, are not deleted.

Example

import Medusa from "@medusajs/medusa-js"
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
// must be previously logged in or use api token
medusa.admin.taxRates.delete(taxRateId)
.then(({ id, object, deleted }) => {
  console.log(id);
})

Parameters

idstringRequired

The tax rate's ID.

customHeadersRecord<string, any>Required

Custom headers to attach to the request.

Default: {}

Returns

ResponsePromiseResponsePromise<DeleteResponse>Required

Resolves to the deletion operation's details.

---

list

Retrieve a list of tax rates. The tax rates can be filtered by fields such as name or rate passed in the query parameter. The tax rates can also be paginated.

Example

To list tax rates:

import Medusa from "@medusajs/medusa-js"
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
// must be previously logged in or use api token
medusa.admin.taxRates.list()
.then(({ tax_rates, limit, offset, count }) => {
  console.log(tax_rates.length);
})

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

import Medusa from "@medusajs/medusa-js"
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
// must be previously logged in or use api token
medusa.admin.taxRates.list({
  expand: "shipping_options"
})
.then(({ tax_rates, limit, offset, count }) => {
  console.log(tax_rates.length);
})

By default, only the first 50 records are retrieved. You can control pagination by specifying the limit and offset properties:

import Medusa from "@medusajs/medusa-js"
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
// must be previously logged in or use api token
medusa.admin.taxRates.list({
  expand: "shipping_options",
  limit,
  offset
})
.then(({ tax_rates, limit, offset, count }) => {
  console.log(tax_rates.length);
})

Parameters

queryAdminGetTaxRatesParams

Filters and pagination configurations applied to the retrieved tax rates.

customHeadersRecord<string, any>Required

Custom headers to attach to the request.

Default: {}

Returns

ResponsePromiseResponsePromise<AdminTaxRatesListRes>Required

Resolves to the list of tax rates with pagination fields.

---

removeProductTypes

Remove product types from a tax rate. This only removes the association between the product types and the tax rate. It does not delete the product types.

Example

import Medusa from "@medusajs/medusa-js"
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
// must be previously logged in or use api token
medusa.admin.taxRates.removeProductTypes(taxRateId, {
  product_types: [
    productTypeId
  ]
})
.then(({ tax_rate }) => {
  console.log(tax_rate.id);
})

Parameters

idstringRequired

The tax rate's ID.

payloadAdminDeleteTaxRatesTaxRateProductTypesReqRequired

The product types to remove from the tax rate.

queryAdminDeleteTaxRatesTaxRateProductTypesParams

Configurations to apply on the retrieved tax rate.

customHeadersRecord<string, any>Required

Custom headers to attach to the request.

Default: {}

Returns

ResponsePromiseResponsePromise<AdminTaxRatesRes>Required

Resolves to the tax rate's details.

---

removeProducts

Remove products from a tax rate. This only removes the association between the products and the tax rate. It does not delete the products.

Example

import Medusa from "@medusajs/medusa-js"
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
// must be previously logged in or use api token
medusa.admin.taxRates.removeProducts(taxRateId, {
  products: [
    productId
  ]
})
.then(({ tax_rate }) => {
  console.log(tax_rate.id);
})

Parameters

idstringRequired

The tax rate's ID.

payloadAdminDeleteTaxRatesTaxRateProductsReqRequired

The products to remove from the tax rate.

queryAdminDeleteTaxRatesTaxRateProductsParams

Configurations to apply on the retrieved tax rate.

customHeadersRecord<string, any>Required

Custom headers to attach to the request.

Default: {}

Returns

ResponsePromiseResponsePromise<AdminTaxRatesRes>Required

Resolves to the tax rate's details.

---

removeShippingOptions

Remove shipping options from a tax rate. This only removes the association between the shipping options and the tax rate. It does not delete the shipping options.

Example

import Medusa from "@medusajs/medusa-js"
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
// must be previously logged in or use api token
medusa.admin.taxRates.removeShippingOptions(taxRateId, {
  shipping_options: [
    shippingOptionId
  ]
})
.then(({ tax_rate }) => {
  console.log(tax_rate.id);
})

Parameters

idstringRequired

The tax rate's ID.

payloadAdminDeleteTaxRatesTaxRateShippingOptionsReqRequired

The shipping options to remove from the tax rate.

queryAdminDeleteTaxRatesTaxRateShippingOptionsParams

Configurations to apply on the retrieved tax rate.

customHeadersRecord<string, any>Required

Custom headers to attach to the request.

Default: {}

Returns

ResponsePromiseResponsePromise<AdminTaxRatesRes>Required

Resolves to the tax rate's details.

---

retrieve

Retrieve a tax rate's details.

Example

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

import Medusa from "@medusajs/medusa-js"
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
// must be previously logged in or use api token
medusa.admin.taxRates.retrieve(taxRateId)
.then(({ tax_rate }) => {
  console.log(tax_rate.id);
})

To specify relations that should be retrieved:

import Medusa from "@medusajs/medusa-js"
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
// must be previously logged in or use api token
medusa.admin.taxRates.retrieve(taxRateId, {
  expand: "shipping_options"
})
.then(({ tax_rate }) => {
  console.log(tax_rate.id);
})

Parameters

idstringRequired

The tax rate's ID.

queryAdminGetTaxRatesTaxRateParams

Configurations to apply on retrieved tax rates.

customHeadersRecord<string, any>Required

Custom headers to attach to the request.

Default: {}

Returns

ResponsePromiseResponsePromise<AdminTaxRatesRes>Required

Resolves to the tax rate's details.

---

update

Update a tax rate's details.

Example

import Medusa from "@medusajs/medusa-js"
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
// must be previously logged in or use api token
medusa.admin.taxRates.update(taxRateId, {
  name: "New Tax Rate"
})
.then(({ tax_rate }) => {
  console.log(tax_rate.id);
})

Parameters

idstringRequired

The tax rate's ID.

payloadAdminPostTaxRatesTaxRateReqRequired

The attributes to update in the tax rate.

queryAdminPostTaxRatesTaxRateParams

Configurations to apply on the retrieved tax rate.

customHeadersRecord<string, any>Required

Custom headers to attach to the request.

Default: {}

Returns

ResponsePromiseResponsePromise<AdminTaxRatesRes>Required

Resolves to the tax rate's details.