medusa-store/docs/content/advanced/storefront/use-regions.mdx

---
description: 'Learn how to implement region-related functionalities on your storefront using the REST APIs. This includes showing the customer available regions, showing product prices, and setting the region of a cart.'
addHowToData: true
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# 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 server installed and set up. If not, you can follow our [quickstart guide](../../quickstart/quick-start.mdx) 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 either the [Next.js](../../starters/nextjs-medusa-starter.mdx) or [Gatsby](../../starters/gatsby-medusa-starter.mdx) storefronts.

### JS Client

This guide includes code snippets to send requests to your Medusa server 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](../../js-client/overview.md) and have [created an instance of the client](../../js-client/overview.md#configuration).

### Medusa React

This guide also includes code snippets to send requests to your Medusa server using Medusa React, among other methods.

If you follow the Medusa React code blocks, it's assumed you already have [Medusa React installed](../../medusa-react/overview.md) and have [used MedusaProvider higher in your component tree](../../medusa-react/overview.md#usage).

For requests that use the cart, it's also assumed you already have [used CartProvider higher in your component tree](../../medusa-react/overview.md#cartprovider).

---

## 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/store/#tag/Region/operation/GetRegions) endpoint:

<Tabs groupId="request-type" wrapperClassName="code-tabs">
<TabItem value="client" label="Medusa JS Client" default>

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

</TabItem>
<TabItem value="medusa-react" label="Medusa React">

```tsx
import { Region } from "@medusajs/medusa"
import { useRegions } from "medusa-react"

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

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

export default Regions
```

</TabItem>
<TabItem value="fetch" label="Fetch API">

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

</TabItem>
</Tabs>

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](/api/store/#tag/Product/operation/GetProducts) or [Get a Product](/api/store/#tag/Product/operation/GetProductsProduct) endpoints.

For example:

<Tabs groupId="request-type" wrapperClassName="code-tabs">
<TabItem value="client" label="Medusa JS Client" default>

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

</TabItem>
<TabItem value="medusa-react" label="Medusa React">

```tsx
import { formatVariantPrice } from "medusa-react"

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

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

export default Product
```

</TabItem>
<TabItem value="fetch" label="Fetch API">

```ts
fetch(`<SERVER_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
})
```

</TabItem>
</Tabs>

In this example, you send a request to the List Products endpoint, 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](/api/store/#section/Pagination). 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](../../guides/carts-in-medusa.mdx).

:::

For example:

<Tabs groupId="request-type" wrapperClassName="code-tabs">
<TabItem value="client" label="Medusa JS Client" default>

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

</TabItem>
<TabItem value="medusa-react" label="Medusa React">

```tsx
import { useCart } from "medusa-react"

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

  const { updateCart } = useCart()

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

  // ...
}

export default Cart
```

</TabItem>
<TabItem value="fetch" label="Fetch API">

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

</TabItem>
</Tabs>

In this example, you send a request to the [Update Cart](/api/store/#tag/Cart/operation/PostCartsCart) endpoint. 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.

---

## See Also

- [Implement cart functionalities in your storefront](../../guides/carts-in-medusa.mdx)
- [Implement checkout in your storefront](./how-to-implement-checkout-flow.mdx)