How to Manage Tax Settings

In this document, you’ll learn how to manage tax settings using admin APIs.

Overview

Tax settings are defined per region. You can change the tax settings of a region using the Update Region API Route.

Scenario

You want to add or use the following admin functionalities:

• List available tax providers in a store.
• Change the tax provider of a region.
• Change tax settings of a region.

---

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 Providers

You can list all tax providers of a store using the List Tax Providers API Route:

• Medusa JS Client
• Medusa React
• Fetch API
• cURL

medusa.admin.store.listTaxProviders()
.then(({ tax_providers }) => {
  console.log(tax_providers.length)
})

import { useAdminStoreTaxProviders } from "medusa-react"

const TaxProviders = () => {
  const { 
    tax_providers,
    isLoading,
  } = useAdminStoreTaxProviders()

  return (
    <div>
      {isLoading && <span>Loading...</span>}
      {tax_providers && !tax_providers.length && (
        <span>No Tax Providers</span>
      )}
      {tax_providers && tax_providers.length > 0 && (
        <ul>
          {tax_providers.map((tax_provider) => (
            <li key={tax_provider.id}>{tax_provider.id}</li>
          ))}
        </ul>
      )}
    </div>
  )
}

export default TaxProviders

fetch(`<BACKEND_URL>/admin/store/tax-providers`, {
  credentials: "include",
})
.then((response) => response.json())
.then(({ tax_providers }) => {
  console.log(tax_providers.length)
})

curl -L -X GET '<BACKEND_URL>/admin/store/tax-providers' \
-H 'x-medusa-access-token: <API_TOKEN>'

This API Route doesn't accept any parameters.

The request returns an array of tax provider objects.

---

Change Tax Provider of a Region

You can change the tax provider of a region using the Update Region API Route:

• Medusa JS Client
• Medusa React
• Fetch API
• cURL

medusa.admin.regions.update(regionId, {
  tax_provider_id,
})
.then(({ region }) => {
  console.log(region.id)
})

import { useAdminUpdateRegion } from "medusa-react"

type Props = {
  regionId: string
}

const Region = ({ regionId }: Props) => {
  const updateRegion = useAdminUpdateRegion(regionId)
  // ...

  const handleUpdate = (taxProviderId: string) => {
    updateRegion.mutate({
      tax_provider_id: taxProviderId,
    })
  }

  // ...
}

export default Region

fetch(`<BACKEND_URL>/admin/regions/${regionId}`, {
  credentials: "include",
  method: "POST",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    tax_provider_id,
  }),
})
.then((response) => response.json())
.then(({ region }) => {
  console.log(region.id)
})

curl -L -X POST '<BACKEND_URL>/admin/regions/<REGION_ID>' \
-H 'x-medusa-access-token: <API_TOKEN>' \
-H 'Content-Type: application/json' \
--data-raw '{
    "tax_provider_id": "<TAX_PROVIDER_ID>"
}'

This API Route requires the ID of the region to be passed as a path parameter.

In the body of the request, you can pass any of the region’s attributes to update. To update the tax provider of a region, you can pass the tax_provider_id request body parameter.

The request returns the updated region as an object.

---

Change Tax Settings of a Region

In addition to changing the tax provider, you can use the same Update Region API Route to update the region’s other tax settings:

• Medusa JS Client
• Medusa React
• Fetch API
• cURL

medusa.admin.regions.update(regionId, {
  tax_provider_id,
  automatic_taxes,
  gift_cards_taxable,
  tax_code,
  tax_rate,
})
.then(({ region }) => {
  console.log(region.id)
})

import { useAdminUpdateRegion } from "medusa-react"

type RegionData = {
  tax_provider_id: string
  automatic_taxes?: boolean
  gift_cards_taxable?: boolean
  tax_code: string
  tax_rate: number
}

type Props = {
  regionId: string
}

const Region = ({ regionId }: Props) => {
  const updateRegion = useAdminUpdateRegion(regionId)
  // ...

  const handleUpdate = (data: RegionData) => {
    updateRegion.mutate(data)
  }

  // ...
}

export default Region

fetch(`<BACKEND_URL>/admin/regions/${regionId}`, {
  credentials: "include",
  method: "POST",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    tax_provider_id,
    automatic_taxes,
    gift_cards_taxable,
    tax_code,
    tax_rate,
  }),
})
.then((response) => response.json())
.then(({ region }) => {
  console.log(region.id)
})

curl -L -X POST '<BACKEND_URL>/admin/regions/<REGION_ID>' \
-H 'x-medusa-access-token: <API_TOKEN>' \
-H 'Content-Type: application/json' \
--data-raw '{
    "tax_provider_id": "<TAX_PROVIDER_ID>",
    "automatic_taxes": true,
    "gift_cards_taxable": true,
    "tax_code": "<TAX_CODE>",
    "tax_rate": 10
}'

You can pass the following parameters in the body of the request that are related to tax settings:

• automatic_taxes: a boolean value indicating whether taxes should be calculated automatically when calculating totals. The default value is true.
• gift_cards_taxable: a boolean value indicating whether gift cards are taxable. The default value is true.
• tax_code: a string indicating the tax code of the region.
• tax_rate: a number indicating the default tax rate of the region.

The request returns the updated region as an object.