175 lines
5.2 KiB
Plaintext
175 lines
5.2 KiB
Plaintext
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.md) 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.md) or [Gatsby](../../starters/gatsby-medusa-starter.md) 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.
|
||
|
||
---
|
||
|
||
## What’s Next
|
||
|
||
- Learn [how to implement cart functionalities in your storefront](../../guides/carts-in-medusa.mdx)
|
||
- Learn [how to implement checkout in your storefront](./how-to-implement-checkout-flow.mdx) |