docs: added region-related documentation pages (#2845)

* docs: added region doc pages

* docs: small fixes

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

@@ -0,0 +1,175 @@
+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)