How to Manage Currencies Using Admin APIs

In this document, you’ll learn how to manage currencies using the Admin APIs.

Overview

The currencies admin APIs allow you to manage currencies in your commerce store.

Currencies are available in your commerce system, even if they’re not added to the store. This guide explains how to manage currencies globally, and how to manage them from a store’s context.

Scenario

You want to add or use the following admin functionalities:

• List currencies
• Update a currency
• Manage currencies in a store including listing, adding, and removing currencies from a store.

Note

As explained in the Currencies architecture guide, currencies are created through migrations. So, you can’t create a currency through the admin APIs.

---

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 Currencies

You can list all available currencies in your system by sending a request to the List Currencies API Route:

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

medusa.admin.currencies.list()
.then(({ currencies, count, offset, limit }) => {
  console.log(currencies.length)
})

import { Currency } from "@medusajs/medusa"
import { useAdminCurrencies } from "medusa-react"

const Currencies = () => {
  const { currencies, isLoading } = useAdminCurrencies()

  return (
    <div>
      {isLoading && <span>Loading...</span>}
      {currencies && !currencies.length && (
        <span>No Currencies</span>
      )}
      {currencies && currencies.length > 0 && (
        <ul>
          {currencies.map((currency: Currency) => (
            <li key={currency.code}>{currency.name}</li>
          ))}
        </ul>
      )}
    </div>
  )
}

export default Currencies

fetch(`<BACKEND_URL>/admin/currencies`, {
  credentials: "include",
})
.then((response) => response.json())
.then(({ currencies, count, offset, limit }) => {
  console.log(currencies.length)
})

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

This API Route accepts optional filter and search query parameters. For example, you can pass the code query parameter to search the list of currencies by a code. You can learn about available query parameters in the API reference.

This request returns an array of currencies along with pagination parameters.

---

Update Currencies

You can update a currency by sending a request to the Update Currency API Route:

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

medusa.admin.currencies.update(code, {
  includes_tax: true,
})
.then(({ currency }) => {
  console.log(currency.code)
})

import { useAdminUpdateCurrency } from "medusa-react"

const Currency = (currencyCode: string) => {
  const updateCurrency = useAdminUpdateCurrency(currencyCode)
  // ...

  const handleUpdate = (includes_tax: boolean) => {
    updateCurrency.mutate({
      includes_tax,
    }, {
      onSuccess: ({ currency }) => {
        console.log(currency)
      }
    })
  }

  // ...
}

export default Currency

fetch(`<BACKEND_URL>/admin/currencies/${code}`, {
    credentials: "include",
    method: "POST",
    headers: {
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      includes_tax,
    }),
  })
  .then((response) => response.json())
  .then(({ currency }) => {
    console.log(currency.code)
  })

curl -L -X GET '<BACKEND_URL>/admin/currencies/<CODE>' \
-H 'x-medusa-access-token: <API_TOKEN>' \
-H 'Content-Type: application/json' \
--data-raw '{
    "includes_tax": true
}'

This API Route requires the currency code as a path parameter.

In the request body parameter, it accepts the field includes_tax which is a boolean value that indicates whether tax inclusion is enabled for the currency. This is only available if you’ve enabled the Tax Inclusive feature.

Tip

You can learn more in the Tax-Inclusive Pricing guide.

The request returns the updated currency as an object.

---

Manage Currencies in a Store

This section explains how you can manage the currencies of a store.

List Currencies in a Store

You can list currencies in a store by sending a request to the Get Store Details API Route:

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

medusa.admin.store.retrieve()
.then(({ store }) => {
  console.log(store.currencies, store.default_currency)
})

import { Currency } from "@medusajs/medusa"
import { useAdminStore } from "medusa-react"

const StoreCurrencies = () => {
  const { store, isLoading } = useAdminStore()

  return (
    <div>
      {isLoading && <span>Loading...</span>}
      {store && store.default_currency && (
        <span>
          Default Currency: {store.default_currency.code}
        </span>
      )}
      {store && !store.currencies.length && (
        <span>No Currencies</span>
      )}
      {store?.currencies && store.currencies.length > 0 && (
        <ul>
          {store.currencies.map((currency: Currency) => (
            <li key={currency.code}>{currency.name}</li>
          ))}
        </ul>
      )}
    </div>
  )
}

export default StoreCurrencies

fetch(`<BACKEND_URL>/admin/store`, {
  credentials: "include",
})
.then((response) => response.json())
.then(({ store }) => {
  console.log(store.currencies, store.default_currency)
})

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

This request returns the store as an object. In that object, there are two properties related to currencies:

1. default_currency is a currency object with details about the default currency.
2. currencies is an array of currency objects.

Add Currency to the Store

You can add a currency to a store using the Add a Currency Code API Route:

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

medusa.admin.store.addCurrency(code)
.then(({ store }) => {
  console.log(store.currencies)
})

import { useAdminAddStoreCurrency } from "medusa-react"

const Store = () => {
  const addCurrency = useAdminAddStoreCurrency()
  // ...

  const handleAdd = (code: string) => {
    addCurrency.mutate(code, {
      onSuccess: ({ store }) => {
        console.log(store.currencies)
      }
    })
  }

  // ...
}

export default Store

fetch(`<BACKEND_URL>/admin/store/currencies/${code}`, {
  credentials: "include",
  method: "POST",
})
.then((response) => response.json())
.then(({ store }) => {
  console.log(store.currencies)
})

curl -L -X POST '<BACKEND_URL>/admin/store/currencies/<CODE>' \
-H 'x-medusa-access-token: <API_TOKEN>'

This API Route requires the currency code to be passed as a path parameter.

The request returns the updated store as an object. You can access the new list of currencies under the store.currencies property.

Delete a Currency from the Store

You can remove a currency from a store by sending a request to the Delete Currency Code API Route:

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

medusa.admin.store.deleteCurrency(code)
.then(({ store }) => {
  console.log(store.currencies)
})

import { useAdminDeleteStoreCurrency } from "medusa-react"

const Store = () => {
  const deleteCurrency = useAdminDeleteStoreCurrency()
  // ...

  const handleAdd = (code: string) => {
    deleteCurrency.mutate(code, {
      onSuccess: ({ store }) => {
        console.log(store.currencies)
      }
    })
  }

  // ...
}

export default Store

fetch(`<BACKEND_URL>/admin/store/currencies/${code}`, {
  credentials: "include",
  method: "DELETE",
})
.then((response) => response.json())
.then(({ store }) => {
  console.log(store.currencies)
})

curl -L -X DELETE '<BACKEND_URL>/admin/store/currencies/<CODE>' \
-H 'x-medusa-access-token: <API_TOKEN>'

This API Route requires the currency code to be passed as a path parameter.

The request returns the updated store as an object. You can access the new list of currencies under the store.currencies property.

---

See Also

• Currency architecture
• How to manage regions