Tax Rates

Queries and Mutations listed here are used to send requests to the Admin Tax Rate API Routes.

All hooks listed 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.

Mutations

useAdminCreateTaxRate

This hook creates a tax rate.

Example

import React from "react"
import { useAdminCreateTaxRate } from "medusa-react"

type Props = {
  regionId: string
}

const CreateTaxRate = ({ regionId }: Props) => {
  const createTaxRate = useAdminCreateTaxRate()
  // ...

  const handleCreate = (
    code: string,
    name: string,
    rate: number
  ) => {
    createTaxRate.mutate({
      code,
      name,
      region_id: regionId,
      rate,
    }, {
      onSuccess: ({ tax_rate }) => {
        console.log(tax_rate.id)
      }
    })
  }

  // ...
}

export default CreateTaxRate

Mutation Function Parameters

AdminPostTaxRatesReqAdminPostTaxRatesReqRequired

The details of the tax rate to create.

Mutation Function Returned Data

AdminTaxRatesResAdminTaxRatesResRequired

The tax rate's details.

useAdminUpdateTaxRate

This hook updates a tax rate's details.

Example

import React from "react"
import { useAdminUpdateTaxRate } from "medusa-react"

type Props = {
  taxRateId: string
}

const TaxRate = ({ taxRateId }: Props) => {
  const updateTaxRate = useAdminUpdateTaxRate(taxRateId)
  // ...

  const handleUpdate = (
    name: string
  ) => {
    updateTaxRate.mutate({
      name
    }, {
      onSuccess: ({ tax_rate }) => {
        console.log(tax_rate.name)
      }
    })
  }

  // ...
}

export default TaxRate

Hook Parameters

idstringRequired

The tax rate's ID.

Mutation Function Parameters

AdminPostTaxRatesTaxRateReqAdminPostTaxRatesTaxRateReqRequired

The details to update of the tax rate.

Mutation Function Returned Data

AdminTaxRatesResAdminTaxRatesResRequired

The tax rate's details.

useAdminDeleteTaxRate

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

Example

import React from "react"
import { useAdminDeleteTaxRate } from "medusa-react"

type Props = {
  taxRateId: string
}

const TaxRate = ({ taxRateId }: Props) => {
  const deleteTaxRate = useAdminDeleteTaxRate(taxRateId)
  // ...

  const handleDelete = () => {
    deleteTaxRate.mutate(void 0, {
      onSuccess: ({ id, object, deleted }) => {
        console.log(id)
      }
    })
  }

  // ...
}

export default TaxRate

Hook Parameters

idstringRequired

The tax rate's ID.

Mutation Function Returned Data

DeleteResponseDeleteResponseRequired

The response returned for a DELETE request.

useAdminCreateProductTaxRates

This hook adds products to a tax rate.

Example

import React from "react"
import { useAdminCreateProductTaxRates } from "medusa-react"

type Props = {
  taxRateId: string
}

const TaxRate = ({ taxRateId }: Props) => {
  const addProduct = useAdminCreateProductTaxRates(taxRateId)
  // ...

  const handleAddProduct = (productIds: string[]) => {
    addProduct.mutate({
      products: productIds,
    }, {
      onSuccess: ({ tax_rate }) => {
        console.log(tax_rate.products)
      }
    })
  }

  // ...
}

export default TaxRate

Hook Parameters

idstringRequired

The tax rate's ID.

Mutation Function Parameters

AdminPostTaxRatesTaxRateProductsReqAdminPostTaxRatesTaxRateProductsReqRequired

The details of the products to associat with the tax rate.

Mutation Function Returned Data

AdminTaxRatesResAdminTaxRatesResRequired

The tax rate's details.

useAdminDeleteProductTaxRates

This hook removes 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 React from "react"
import { useAdminDeleteProductTaxRates } from "medusa-react"

type Props = {
  taxRateId: string
}

const TaxRate = ({ taxRateId }: Props) => {
  const removeProduct = useAdminDeleteProductTaxRates(taxRateId)
  // ...

  const handleRemoveProduct = (productIds: string[]) => {
    removeProduct.mutate({
      products: productIds,
    }, {
      onSuccess: ({ tax_rate }) => {
        console.log(tax_rate.products)
      }
    })
  }

  // ...
}

export default TaxRate

Hook Parameters

idstringRequired

The tax rate's ID.

Mutation Function Parameters

AdminDeleteTaxRatesTaxRateProductsReqAdminDeleteTaxRatesTaxRateProductsReqRequired

The details of the products to remove their associated with the tax rate.

Mutation Function Returned Data

AdminTaxRatesResAdminTaxRatesResRequired

The tax rate's details.

useAdminCreateProductTypeTaxRates

This hook adds product types to a tax rate.

Example

import React from "react"
import { 
  useAdminCreateProductTypeTaxRates,
} from "medusa-react"

type Props = {
  taxRateId: string
}

const TaxRate = ({ taxRateId }: Props) => {
  const addProductTypes = useAdminCreateProductTypeTaxRates(
    taxRateId
  )
  // ...

  const handleAddProductTypes = (productTypeIds: string[]) => {
    addProductTypes.mutate({
      product_types: productTypeIds,
    }, {
      onSuccess: ({ tax_rate }) => {
        console.log(tax_rate.product_types)
      }
    })
  }

  // ...
}

export default TaxRate

Hook Parameters

idstringRequired

The tax rate's ID.

Mutation Function Parameters

AdminPostTaxRatesTaxRateProductTypesReqAdminPostTaxRatesTaxRateProductTypesReqRequired

The product types to add to the tax rate.

Mutation Function Returned Data

AdminTaxRatesResAdminTaxRatesResRequired

The tax rate's details.

useAdminDeleteProductTypeTaxRates

This hook removes 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 React from "react"
import { 
  useAdminDeleteProductTypeTaxRates,
} from "medusa-react"

type Props = {
  taxRateId: string
}

const TaxRate = ({ taxRateId }: Props) => {
  const removeProductTypes = useAdminDeleteProductTypeTaxRates(
    taxRateId
  )
  // ...

  const handleRemoveProductTypes = (
    productTypeIds: string[]
  ) => {
    removeProductTypes.mutate({
      product_types: productTypeIds,
    }, {
      onSuccess: ({ tax_rate }) => {
        console.log(tax_rate.product_types)
      }
    })
  }

  // ...
}

export default TaxRate

Hook Parameters

idstringRequired

The tax rate's ID.

Mutation Function Parameters

AdminDeleteTaxRatesTaxRateProductTypesReqAdminDeleteTaxRatesTaxRateProductTypesReqRequired

Product types to remove from the tax rates.

Mutation Function Returned Data

AdminTaxRatesResAdminTaxRatesResRequired

The tax rate's details.

useAdminCreateShippingTaxRates

This hook adds shipping options to a tax rate.

Example

import React from "react"
import { useAdminCreateShippingTaxRates } from "medusa-react"

type Props = {
  taxRateId: string
}

const TaxRate = ({ taxRateId }: Props) => {
  const addShippingOption = useAdminCreateShippingTaxRates(
    taxRateId
  )
  // ...

  const handleAddShippingOptions = (
    shippingOptionIds: string[]
  ) => {
    addShippingOption.mutate({
      shipping_options: shippingOptionIds,
    }, {
      onSuccess: ({ tax_rate }) => {
        console.log(tax_rate.shipping_options)
      }
    })
  }

  // ...
}

export default TaxRate

Hook Parameters

idstringRequired

The tax rate's ID.

Mutation Function Parameters

AdminPostTaxRatesTaxRateShippingOptionsReqAdminPostTaxRatesTaxRateShippingOptionsReqRequired

The details of the shipping options to associate with the tax rate.

Mutation Function Returned Data

AdminTaxRatesResAdminTaxRatesResRequired

The tax rate's details.

useAdminDeleteShippingTaxRates

This hook removes 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 React from "react"
import { useAdminDeleteShippingTaxRates } from "medusa-react"

type Props = {
  taxRateId: string
}

const TaxRate = ({ taxRateId }: Props) => {
  const removeShippingOptions = useAdminDeleteShippingTaxRates(
    taxRateId
  )
  // ...

  const handleRemoveShippingOptions = (
    shippingOptionIds: string[]
  ) => {
    removeShippingOptions.mutate({
      shipping_options: shippingOptionIds,
    }, {
      onSuccess: ({ tax_rate }) => {
        console.log(tax_rate.shipping_options)
      }
    })
  }

  // ...
}

export default TaxRate

Hook Parameters

idstringRequired

The tax rate's ID.

Mutation Function Parameters

AdminDeleteTaxRatesTaxRateShippingOptionsReqAdminDeleteTaxRatesTaxRateShippingOptionsReqRequired

The details of the shipping options to remove their associate with the tax rate.

Mutation Function Returned Data

AdminTaxRatesResAdminTaxRatesResRequired

The tax rate's details.

---

Queries

useAdminTaxRates

This hook retrieves 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 React from "react"
import { useAdminTaxRates } from "medusa-react"

const TaxRates = () => {
  const { 
    tax_rates, 
    isLoading
  } = useAdminTaxRates()

  return (
    <div>
      {isLoading && <span>Loading...</span>}
      {tax_rates && !tax_rates.length && (
        <span>No Tax Rates</span>
      )}
      {tax_rates && tax_rates.length > 0 && (
        <ul>
          {tax_rates.map((tax_rate) => (
            <li key={tax_rate.id}>{tax_rate.code}</li>
          ))}
        </ul>
      )}
    </div>
  )
}

export default TaxRates

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

import React from "react"
import { useAdminTaxRates } from "medusa-react"

const TaxRates = () => {
  const { 
    tax_rates, 
    isLoading
  } = useAdminTaxRates({
    expand: ["shipping_options"]
  })

  return (
    <div>
      {isLoading && <span>Loading...</span>}
      {tax_rates && !tax_rates.length && (
        <span>No Tax Rates</span>
      )}
      {tax_rates && tax_rates.length > 0 && (
        <ul>
          {tax_rates.map((tax_rate) => (
            <li key={tax_rate.id}>{tax_rate.code}</li>
          ))}
        </ul>
      )}
    </div>
  )
}

export default TaxRates

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

import React from "react"
import { useAdminTaxRates } from "medusa-react"

const TaxRates = () => {
  const { 
    tax_rates, 
    limit,
    offset,
    isLoading
  } = useAdminTaxRates({
    expand: ["shipping_options"],
    limit: 10,
    offset: 0
  })

  return (
    <div>
      {isLoading && <span>Loading...</span>}
      {tax_rates && !tax_rates.length && (
        <span>No Tax Rates</span>
      )}
      {tax_rates && tax_rates.length > 0 && (
        <ul>
          {tax_rates.map((tax_rate) => (
            <li key={tax_rate.id}>{tax_rate.code}</li>
          ))}
        </ul>
      )}
    </div>
  )
}

export default TaxRates

Hook Parameters

queryAdminGetTaxRatesParams

Filters and pagination configurations applied to the retrieved tax rates.

Query Returned Data

limitnumberRequired

The maximum number of items that can be returned in the list.

offsetnumberRequired

The number of items skipped before the returned items in the list.

countnumberRequired

The total number of items available.

tax_ratesTaxRate[]Required

An array of tax rate details.

useAdminTaxRate

This hook retrieves a tax rate's details.

Example

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

import React from "react"
import { useAdminTaxRate } from "medusa-react"

type Props = {
  taxRateId: string
}

const TaxRate = ({ taxRateId }: Props) => {
  const { tax_rate, isLoading } = useAdminTaxRate(taxRateId)

  return (
    <div>
      {isLoading && <span>Loading...</span>}
      {tax_rate && <span>{tax_rate.code}</span>}
    </div>
  )
}

export default TaxRate

To specify relations that should be retrieved:

import React from "react"
import { useAdminTaxRate } from "medusa-react"

const TaxRate = (taxRateId: string) => {
  const { tax_rate, isLoading } = useAdminTaxRate(taxRateId, {
    expand: ["shipping_options"]
  })

  return (
    <div>
      {isLoading && <span>Loading...</span>}
      {tax_rate && <span>{tax_rate.code}</span>}
    </div>
  )
}

export default TaxRate

Hook Parameters

idstringRequired

The tax rate's ID.

queryAdminGetTaxRatesParams

Configurations to apply on retrieved tax rates.

Query Returned Data

tax_rateTaxRateRequired

Tax rate details.