In this guide, you'll learn how the storefront picks a sales region for a first-time visitor, how to enable an IP lookup through ip-api, and how to add a detection provider of your own.

A visitor who has never opened the store has no region yet. Rather than falling back to whichever region the backend happens to return first, the storefront resolves their country in the middleware and stores it in the _medusa_country cookie, which every page and the cart then read. Detection itself is a pluggable provider, the same way address autocomplete is.

resolveGeolocationProvider reads the active provider from an environment variable and switches on it:

src/lib/geolocation/detect.ts
1export const resolveGeolocationProvider = (): GeolocationProvider => {
2  switch (true) {
3    case isIpApi(geolocationProvider):
4      return ipApiProvider
5    default:
6      return platformProvider
7  }
8}

geolocationProvider reads GEOLOCATION_PROVIDER and isIpApi checks it for the ip-api value, both in the same file. Any other value, including an unset variable, falls through to platformProvider, which reads the geo headers your hosting platform already sets.

The middleware touches the feature in one place. resolveCountry returns a function that writes the cookie onto whichever response the request ends up returning, so cookie precedence, the fallback chain, and the debug headers all stay inside src/lib/geolocation:

src/middleware.ts
const applyCountry = await resolveCountry(request, regionMap)

The order it resolves in is the same for every provider: an existing _medusa_country cookie wins, then the provider's answer, then NEXT_PUBLIC_DEFAULT_REGION, then the first region the backend returned. The cookie comes first because the region switcher in the header writes to it, and detection must never override a choice the visitor made themselves.

The default provider needs no configuration and makes no network call. It reads the country your platform already resolved, in this order:

Values that mean "country unknown", xx, t1 and zz, are discarded rather than treated as a country, because a region lookup for xx fails and drops the visitor into the fallback chain.

On Vercel and Cloudflare this is all you need. The header is free, instant, and more accurate than any third-party lookup, so leave GEOLOCATION_PROVIDER unset there.

Deployments without geo headers, and local development, need a real lookup. Set the provider in apps/storefront/.env.local:

apps/storefront/.env.local
1GEOLOCATION_PROVIDER=ip-api
2GEOLOCATION_PROVIDER_API_KEY=

Neither variable is prefixed with NEXT_PUBLIC_, because detection runs only on the server and the key must stay out of the browser bundle.

The provider checks the platform headers first and calls ip-api only when none of them carried a country, so enabling it on Vercel costs nothing. A successful lookup for a visitor's IP is cached for an hour, and concurrent requests for the same IP are collapsed into a single call. The provider also honours ip-api's rate limit budget: it reads the X-Rl and X-Ttl response headers and stops calling for X-Ttl seconds once the budget is spent or a 429 comes back, which is what keeps a busy store from being banned for an hour.

resolveClientIp reads x-forwarded-for first, then cf-connecting-ip, true-client-ip, x-real-ip, x-client-ip and fly-client-ip, and normalizes what it finds: it strips a port, strips IPv6 brackets, and unwraps an IPv4-mapped IPv6 address, so ::ffff:127.0.0.1 is recognized as the loopback address 127.0.0.1. What it ends up with picks one of three behaviors:

The middle row is what makes localhost and a LAN address resolve to the country the machine actually browses from, in next dev and in a build and start run alike. Because nothing is cached there, switching a VPN and clearing _medusa_country changes the region on the next request. It costs one lookup per cookieless page load, which is why it is limited to visitors on the server's own network.

The last row is deliberately not a guess. Geolocating the server's egress address for a visitor whose IP is unknown would pin every such visitor to the country of the datacentre. If a deployment resolves no country at all, the reverse proxy in front of it is not forwarding x-forwarded-for.

Set GEOLOCATION_DEBUG=true and the middleware annotates every response with what it decided. The flag works in any mode, a production build included:

apps/storefront/.env.local
GEOLOCATION_DEBUG=true

Open the network panel, reload, and read the headers on the document request. x-geo-source: cookie means the cookie was never cleared, x-geo-provider: platform means GEOLOCATION_PROVIDER never reached the server, and a fallback-* source names which link in the chain answered.

A country the middleware could not resolve is stored for five minutes instead of a year, so one failed lookup can't pin a visitor to the fallback region for good. A country the visitor picked in the region switcher, and one that was really detected, are both kept for a year.

Every provider implements the same two-field contract:

src/lib/geolocation/types.ts
1export type GeolocationContext = {
2  headers: Headers
3  cf?: { country?: string | null }
4}
5
6export type GeolocationProvider = {
7  name: string
8  lookup: (context: GeolocationContext) => Promise<string | null>
9}

lookup returns a lowercase ISO 3166-1 alpha-2 code, or null when it resolved nothing. name is not decoration: it goes into the cache key, so two providers never read each other's results.

To add a provider for another service, or a local database such as MaxMind GeoLite2:

1. Create a file under providers/ that exports a GeolocationProvider. Call countryFromPlatform from providers/platform.ts first if you want the free header to keep winning, and wrap any network call in withLookupCache from lookup-cache.ts to get the hour-long cache and the concurrent-request collapsing.
2. Add a case for it in the resolveGeolocationProvider switch shown above, alongside a small isYourProvider(provider?: string) helper next to isIpApi.
3. Point GEOLOCATION_PROVIDER at the id your case and helper check for.

providers/platform.ts is the shorter example to model on, at 50 lines with no network call at all. providers/ip-api.ts shows what a real lookup adds: a timeout, a rate-limit budget, and the three-way branch on the client address.