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 and JavaScript’s Fetch API.

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).

---

## 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>

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

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

```tsx
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>

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

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

```tsx
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>

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

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

```tsx
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)