Store Selected Region in the Storefront

In this guide, you'll learn how to store a customer's selected region in your storefront, then retrieve it for later use.

Why Select and Store Region?

Prices, taxes, and available payment methods vary between regions. Customers should see the correct amounts for their country.

The Aiminaabee store code (NEXT_PUBLIC_DEFAULT_STORE_CODE) is not a region. Do not persist a country ISO as the store code.

Next.js: country in the URL

The Next.js template puts the customer's country in the route: app/[countryCode]/(store)/….

1. List regions with sdk.store.region.list(storeCode).
2. Map each region's countries[].iso_2 to that region.
3. Resolve getRegion(storeCode, countryCode) from the URL param.
4. Pass region.id as region_id when listing products or creating/updating the cart.

When the customer switches country, navigate to /{newCountry}/… and let getOrSetCart update the cart's region_id if it changed.

1"use server"
2
3export const getRegion = async (
4  storeCode: string,
5  countryCode: string
6): Promise<HttpTypes.StoreRegion | null> => {
7  const { regions } = await sdk.store.region.list(storeCode)
8  const map = new Map<string, HttpTypes.StoreRegion>()
9
10  regions.forEach((region) => {
11    region.countries?.forEach((country) => {
12      const iso = (country?.iso_2 ?? "").toLowerCase()
13      if (iso) {
14        map.set(iso, region)
15      }
16    })
17  })
18
19  return map.get(countryCode.toLowerCase()) ?? null
20}

See Build a Next.js Storefront and List Regions.

SPA: persist a region ID

If you are not using URL-based countries, show the region list from List Regions and persist the chosen region's ID (cookie preferred over localStorage).

Retrieve it later with the Retrieve Region API route:

1sdk.store.region.retrieve(storeCode, regionId)
2.then(({ region }) => {
3  console.log(region)
4})

Region React Context

A client RegionProvider is for SPAs. On Next.js, resolve the region on the server from [countryCode]. See Region React Context.