Use Regions in the Storefront

In this document, you’ll learn how to use Regions in the storefront.

Overview

Regions represent the supported countries and currencies in your store. Customers can use the region that fits them based on their country and currency.

Scenario

You want to implement the following in your storefront:

• Show customers available regions.
• Show product prices based on the selected region.
• Set a cart’s region to the selected region.

---

Prerequisites

Medusa Components

It's assumed that you already have a Medusa backend installed and set up. If not, you can follow our quickstart guide to get started.

It is also assumed you already have a storefront set up. It can be a custom storefront or one of Medusa’s storefronts. If you don’t have a storefront set up, you can install the Next.js Starter Template.

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.

For requests that use the cart, it's also assumed you already have used CartProvider higher in your component tree.

---

Show List of Regions

Customers should be able to see the list of available regions and select their region.

You can retrieve available regions by sending a request to the List Regions API Route:

• Medusa JS Client
• Medusa React
• Fetch API

medusa.regions.list()
.then(({ regions }) => {
  console.log(regions.length)
  // show customers available regions
})

import { useRegions } from "medusa-react"

const Regions = () => {
  const { regions, isLoading } = useRegions()

  return (
    <div>
      {isLoading && <span>Loading...</span>}
      {regions?.length && (
        <ul>
          {regions.map((region) => (
            <li key={region.id}>
              {region.name}
            </li>
          ))}
        </ul>
      )}
    </div>
  )
}

export default Regions

fetch(`<BACKEND_URL>/store/regions`, {
  credentials: "include",
})
.then((response) => response.json())
.then(({ regions }) => {
  console.log(regions.length)
  // show customers available regions
})

This request returns the list of available regions. You can show them to your customers to select their region.

When a customer selects a region, you should store that region’s ID. You’ll need it to show the customer product prices based on the selected region, and set the region of their cart.

---

Show Product Prices Based on the Selected Region

To retrieve products with the prices based on the selected regions, you can pass the region_id query parameter to the List Products or Get a Product API Routes.

For example:

• Medusa JS Client
• Medusa React
• Fetch API

medusa.products.list({
  region_id: regionId,
})
.then(({ products, limit, offset, count }) => {
  console.log(products.length)
  // show customer the products
})

import { formatVariantPrice } from "medusa-react"

const Product = () => {
  // retrieve the region and variant(s)
  // ...

  return (
    <span>
      {formatVariantPrice({
        variant, // ProductVariant
        region, // Region
      })}
    </span>
  )
}

export default Product

fetch(`<BACKEND_URL>/store/products?region_id=${regionId}`, {
  credentials: "include",
})
.then((response) => response.json())
.then(({ products, limit, offset, count }) => {
  console.log(products.length)
  // show customer the products
})

In this example, you send a request to the List Products API Route, passing it the region_id query parameter. It is assumed that you have the ID of the region stored in the variable regionId.

This request returns the list of products along with pagination fields. The prices of the products are based on the selected region.

---

Set a Cart’s Region

When the customer changes their region, you must also reflect that change on their cart.

You can set the cart’s region while creating it and later on by updating it.

Tip

You can learn how to implement cart functionalities in your storefront in this documentation.

For example:

• Medusa JS Client
• Medusa React
• Fetch API

medusa.carts.update(cartId, {
  region_id: regionId,
})
.then(({ cart }) => {
  console.log(cart.id)
})

import { useCart } from "medusa-react"

const Cart = () => {
  // ...

  const { updateCart } = useCart()

  const changeRegionId = (region_id: string) => {
    updateCart.mutate({
      region_id,
    })
  }

  // ...
}

export default Cart

fetch(`<BACKEND_URL>/store/carts/${cartId}`, {
  method: "POST",
  credentials: "include",
  body: JSON.stringify({
    region_id: regionId,
  }),
})
.then((response) => response.json())
.then(({ cart }) => {
  console.log(cart.id)
})

In this example, you send a request to the Update Cart API Route. In the request’s body, you pass the parameter region_id and set its value to the selected region’s ID. It is assumed that you have the ID of the region stored in the variable regionId.

This request returns the full object of the updated cart.