Skip to main content
Skip to main content

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.
The product types to add to the tax rate.
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.
The products to add to the tax rate.
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.
The shipping options to add to the tax rate.
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.
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

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.
The product types to remove from the tax rate.
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.
The products to remove from the tax rate.
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.
The shipping options to remove from the tax rate.
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.
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.
The attributes to update in the tax rate.
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.
Was this section helpful?