---
title: About market-aware auth URLs for headless stores
description: >-
  Learn how to construct market-aware login and authorization URLs for the
  Customer Account API in headless storefronts using locale and region_country
  parameters.
source_url:
  html: >-
    https://shopify.dev/docs/storefronts/headless/building-with-the-customer-account-api/market-aware-auth-urls
  md: >-
    https://shopify.dev/docs/storefronts/headless/building-with-the-customer-account-api/market-aware-auth-urls.md
api_name: customer
---

# 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:

| Parameter | Controls |
| - | - |
| [`locale`](https://shopify.dev/docs/api/customer#authorization) | Sets the language of the login screen. |
| [`region_country`](https://shopify.dev/docs/api/customer#authorization) | Sets the market context for policies and branding. |

***

## How `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.

***

## Example: market-aware authorization URL

The following example shows how to build an authorization URL with `locale` and `region_country` parameters using the [discovery endpoint](https://shopify.dev/docs/api/customer#discovery-endpoints):

## Market-aware authorization URL

```ts
// 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();
```

***

## Next steps

* Refer to the [Customer Account API authorization reference](https://shopify.dev/docs/api/customer#authorization) for the full list of authorization parameters.
* If using Hydrogen, learn about [internationalization in Hydrogen](https://shopify.dev/docs/storefronts/hydrogen/markets) for handling markets.

***