Skip to main content

About market-aware auth URLs for headless stores

Headless storefronts need to manually construct authorization URLs that include market context. This guide explains the parameters that control the market-aware login experience. It applies to any headless storefront, whether you're using Hydrogen or building a custom implementation.

Two query parameters control the market-aware login experience:

ParameterControls
localeSets the language of the login screen.
region_countrySets the market context for policies and branding.

Anchor to How ,[object Object], and ,[object Object], work togetherHow locale and region_country work together

The locale and region_country parameters can be used independently or together:

  • Setting locale=fr-CA&region_country=CA displays the login screen in French Canadian with Canadian market policies.
  • Setting locale=en&region_country=CA displays the login screen in English but still applies Canadian market policies.
  • Using locale alone changes the language without market-specific context.
  • Using region_country alone applies market-specific policies without changing the language.

If the specified region_country doesn't match a configured market, then the primary market context is used.

The order of locale and region_country parameters in the URL doesn't matter.

Use both parameters together for a fully localized, market-aware login experience. For example, a customer browsing a Canadian French market should see the login screen in French with Canadian market policies applied.

Anchor to Example: market-aware authorization URLExample: market-aware authorization URL

The following example shows how to build an authorization URL with locale and region_country parameters using the discovery endpoint:

Market-aware authorization URL

// Discover the authentication endpoints from the shop's storefront domain
const discoveryResponse = await fetch(
`https://${shopDomain}/.well-known/openid-configuration`
);
const authConfig = await discoveryResponse.json();

// Build the authorization URL using the discovered endpoint
const clientId = process.env.CLIENT_ID;
const authorizationRequestUrl = new URL(authConfig.authorization_endpoint);

// Required parameters
authorizationRequestUrl.searchParams.append(
'scope',
'openid email customer-account-api:full'
);
authorizationRequestUrl.searchParams.append('client_id', clientId);
authorizationRequestUrl.searchParams.append('response_type', 'code');
authorizationRequestUrl.searchParams.append('redirect_uri', `<redirect_uri>`);
authorizationRequestUrl.searchParams.append('state', '<state>');
authorizationRequestUrl.searchParams.append('nonce', '<nonce>');

// Market-aware parameters
// Set the language for the login screen (supports regional variants)
authorizationRequestUrl.searchParams.append('locale', 'fr-CA');
// Set the market context for policies and branding
authorizationRequestUrl.searchParams.append('region_country', 'CA');

// Public client - PKCE flow
const verifier = await generateCodeVerifier();
const challenge = await generateCodeChallenge(verifier);
localStorage.setItem('code-verifier', verifier);

authorizationRequestUrl.searchParams.append('code_challenge', challenge);
authorizationRequestUrl.searchParams.append('code_challenge_method', 'S256');

// Redirect the customer to the market-aware login page
window.location.href = authorizationRequestUrl.toString();

Anchor to Next stepsNext steps

Was this page helpful?