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 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

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.
customHeadersRecord<string, any>Required
Custom headers to attach to the request.

Default: {}

Configurations to apply on retrieved tax rates.

Returns

ResponsePromiseResponsePromise<AdminTaxRatesRes>Required
Resolves to the tax rate'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

customHeadersRecord<string, any>Required
Custom headers to attach to the request.

Default: {}

Filters and pagination configurations applied to the retrieved tax rates.

Returns

ResponsePromiseResponsePromise<AdminTaxRatesListRes>Required
Resolves to the list of tax rates with pagination fields.

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.
customHeadersRecord<string, any>Required
Custom headers to attach to the request.

Default: {}

Configurations to apply on the retrieved tax rate.

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.
customHeadersRecord<string, any>Required
Custom headers to attach to the request.

Default: {}

Configurations to apply on the retrieved tax rate.

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.
customHeadersRecord<string, any>Required
Custom headers to attach to the request.

Default: {}

Configurations to apply on the retrieved tax rate.

Returns

ResponsePromiseResponsePromise<AdminTaxRatesRes>Required
Resolves to the tax rate's details.

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.
customHeadersRecord<string, any>Required
Custom headers to attach to the request.

Default: {}

Configurations to apply on the retrieved tax rate.

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.
customHeadersRecord<string, any>Required
Custom headers to attach to the request.

Default: {}

Configurations to apply on the retrieved tax rate.

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.
customHeadersRecord<string, any>Required
Custom headers to attach to the request.

Default: {}

Configurations to apply on the retrieved tax rate.

Returns

ResponsePromiseResponsePromise<AdminTaxRatesRes>Required
Resolves to the tax rate's details.

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.
customHeadersRecord<string, any>Required
Custom headers to attach to the request.

Default: {}

Configurations to apply on the retrieved tax rate.

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.
customHeadersRecord<string, any>Required
Custom headers to attach to the request.

Default: {}

Configurations to apply on the retrieved tax rate.

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.
Was this section helpful?