Multistore setup

Multistore enables you to run multiple storefronts from a single codebase and content repository. Each storefront can serve different languages, currencies, regions, or brands while sharing core code and maintaining unified content delivery.

What is multistore?

Multistore is useful for:

• Localization: Serving different languages and currencies (for example, English/US, French/Canada) from the same site, with localized content and Commerce data.
• Multiple Brands or Regions: Operating several brands or regional storefronts, each with their own configuration, but sharing core code and content.

There are two main approaches to multistore:

1. Multiple Domains: Each domain is configured as its own Edge Delivery Services site, pointing to the same code and content repository. See Multiple Edge Delivery Services sites on one Fastly service for how to route and configure push invalidation when these sites share one Fastly service.
2. Subfolders (this page): A single domain with subfolders (such as /en/, /fr/) for each locale or store. Each subfolder can have its own localized content and Commerce configuration.

Key features:

• Editorial and Commerce Localization: Editorial content (pages, blocks) and commerce data (products, prices, currencies) are both localized.
• Automated Translation Tools: Tools are provided to automate translation of content and manage updates across languages.
• Configurable Headers: Storefronts can send different headers to the commerce backend to select the correct store, language, and currency.
• Store Switcher: Out-of-the-box UI enables users to switch between stores and locales.
• Automatic Link Management: Links are automatically updated to point to the correct localized version as users navigate.

How it works

Adobe Commerce uses a hierarchical structure to manage multiple stores within a single instance. This structure consists of three levels: websites, stores, and store views. Localization is managed at the store view level, allowing merchants to present the store in different languages and apply the proper currency.

Each store or locale is defined in configuration files. These files specify which headers to send to the commerce backend. They also define which content folders to use and how to structure localized content. The content hierarchy follows Edge Delivery Services best practices, emphasizing a single-tier structure.

Content organization

This walkthrough uses locale folders such as /en/, /en-ca/, and /fr-ca/. Choose a structure that fits your language and regional requirements, as described in Manage shared and localized content. Keep the chosen paths consistent with your storefront configuration.

• Directory/en/ — English store (Default root language)

  • Directoryplaceholders/ — Stores JSON files for text and UI components for the English US store.

    • …
  • index — The home page of the English US store.
  • store-switcher — Manages the list of stores and their URL for the English US store.
• Directory/en-ca/ — English Canadian Store

  • Directoryplaceholders/ — Defines JSON files for text and UI components for the Canadian store.

    • …
  • index — The home page of the English Canadian store.
  • store-switcher — Manages the list of stores and their URL for the Canadian store.

Manage shared and localized content

Choose the content workflow separately from the Commerce store view settings:

• Locale folders within one site: A rollout copies documents from a language folder into regional or locale folders. It does not translate the content. See Strategies for translation, localization, and rollout to plan the structure and Translation projects to run the workflow.

  Review the conflict settings before updating localized content. Rollouts can merge changes into existing documents, but spreadsheets, JSON, and other non-HTML files are always overwritten.

• Shared content across sites: Multi-Site Manager (MSM) lets sites reuse content from a base site and keep local versions of individual pages. Follow that guide to configure the content source and Experience Workspace. MSM is optional for the single-site subfolder approach on this page.

Neither workflow replaces the Commerce headers, store switcher, or product-page setup described below.

Store-specific files

Each store view requires specific files to define the customer experience:

Store switcher: Each store view has its own store-switcher document file (called a fragment). This fragment provides the list of stores to select from by language. The store-switcher component renders a button in the footer that opens a modal containing the stores listed in this document.

Content files: The content files provide the structure of the pages served to your shoppers. They are located in the store view directories and contain the content for each store view. These files are documents hosted on da.live (Document Authoring environment), SharePoint, or Google Docs that are used to generate the store view pages.

Placeholders: JSON files that define reusable variables for text and UI components. Each drop-in component has its own placeholder file—cart.json, checkout.json, pdp.json. These files replace variables in your content files with text values.

For translating placeholder files, see Commerce localization tasks. For technical implementation details, see Labeling and Localizing Drop-In Components.

Prerequisites

Before implementing multistore functionality, ensure you have:

• Your storefront repository linked to Document Authoring environment (da.live) via Edge Delivery Services
• Access to Adobe Commerce Admin for store view configuration
• Your Storefront Configuration set up and pointing to the Adobe Commerce instance
• Familiarity with Authoring and Publishing Content
• Understanding of Storefront Configuration
• Knowledge of Adobe Commerce Configuration Scope

---

Implementation walkthrough

This walkthrough expands a storefront from the United States to the Canadian market with two new locales: Canadian English (en-ca) and Canadian French (fr-ca).

Verify environment setup

Before implementing multistore functionality, confirm your environment is properly configured.

1. Verify the code sync bot is installed on your repository. This automatically configures your site’s content pointer to the Document Authoring environment at da.live.

2. Verify the config.json file (or Configuration Service) is connected to your Adobe Commerce instance to enable content preview, publishing, and editing.

Environment setup

This verification step is crucial as it ensures you can properly preview and publish content for your new store views.

Create the content folder structure

To support the new store views, set up the folder structure in your Document Authoring environment.

1. Navigate to the connected content folder in da.live.

2. Create the Canadian English folder:

   • Select “New folder”
   • Name it en-ca

3. Create the Canadian French folder:

   • Select “New folder”
   • Name it fr-ca

4. Populate /en-ca/ with English content and /fr-ca/ with French content. You can copy documents from /en/, but translate the French content before publishing it. To automate translation and rollout, follow Manage shared and localized content. Review existing destination content before copying or rolling out updates.

Folder naming

Standard format: Use hyphens for locale folders (en-ca, fr-ca) following the language-code-region-code pattern. This aligns with:

• ISO 639-1 (language codes) and ISO 3166-1 (country codes)
• Web URL conventions
• Adobe/AEM.live best practices

Ensure folder names match exactly with Adobe Commerce store view codes and can be used in web addresses.

Configure Adobe Commerce store views

To match your content folder structure, create the corresponding store views in Adobe Commerce Admin.

1. Access Adobe Commerce Admin and navigate to Stores → Settings → All Stores.

2. Create the Canadian English store view:

   • Follow the store view creation process
   • Configure as: one website, one store, one store view
   • Set the store view code to match your folder name (en-ca)

3. Create the Canadian French store view:

   • Repeat the process for the French locale
   • Set the store view code to match your folder name (fr-ca)

Store view codes

The store view codes in Adobe Commerce Admin must exactly match the folder names created in da.live for proper integration.

Provide product pages for each store view

Product detail pages (PDPs) can come from authored documents or HTML supplied through Bring Your Own Markup (BYOM) , such as AEM Commerce Prerender. Existing storefronts may use folder mapping, but it is discouraged for catalog pages and is not required for multistore. See folder mapping guidance and alternatives .

Authored or generated pages

If you do not use folder mapping, customize your authoring or generation implementation for every store view. A locale folder and Commerce configuration alone do not create product pages.

1. Create a document or generate HTML for each product path under every store view, such as /en-ca/products/widget/p12345 and /fr-ca/products/widget/p12345. Include a Product Details block in authored documents, or its equivalent product-details block markup in generated HTML.
2. Set the sku page metadata to the product’s catalog SKU, preserving its original case. For example, the page at /en-ca/products/widget/p12345 can have sku metadata of P12345. For authored pages, set this in the page metadata. For BYOM HTML, include it as <meta name="sku" content="P12345"> or in a metadata block. See SEO metadata for metadata guidance.
3. Preview and publish each page at its full store view path using your content workflow. For generated pages, confirm that your generation and publishing implementation handles each locale path and its intended catalog context; adapt it if needed.

Open a product page in each locale and confirm that it loads the intended product, language, currency, and price. Inspect the document’s <head> in browser developer tools to confirm the sku metadata.

Update folder mapping

Existing folder-mapped implementations only: Skip this section if you use authored pages or BYOM. If your storefront still maps product URLs to a shared template, add a mapping for each store view using the Config Service API. In the example below, /en-ca/products/ uses /en-ca/products/default; the equivalent template must exist for each mapping.

Step 1: Authenticate

Go to https://admin.hlx.page/login, then go to your selected IDP login URL, and sign in. Retrieve the auth token from your browser’s cookie storage (available in Developer Tools → Application → Cookies). Use that token to authenticate Admin API requests, with the headers and request format described in the Config Service setup guide and the Admin API reference .

Step 2: Get the current folder configuration

GET https://admin.hlx.page/config/{ORG}/sites/{SITE}/folders.json
Authorization: token {YOUR_AUTH_TOKEN}

The response is a JSON object mapping URL path prefixes to template document paths, for example:

{
  "/products/": "/products/default"
}

If the request fails, resolve the authentication, permission, or configuration error before continuing.

Step 3: Modify and POST the updated configuration

Add your new store view mappings and POST the complete object back to the same endpoint:

POST https://admin.hlx.page/config/{ORG}/sites/{SITE}/folders.json
Authorization: token {YOUR_AUTH_TOKEN}
Content-Type: application/json

{
  "/en/products/": "/en/products/default",
  "/en-ca/products/": "/en-ca/products/default",
  "/fr-ca/products/": "/fr-ca/products/default"
}

Caution

The POST replaces the entire folders.json object. Always start from the current GET response and include all existing mappings alongside your new ones.

For full details, see the Config Service setup guide and the Admin API reference .

Update site configuration

To include configuration overrides for the new store view, update your storefront config. In this file, you’ll define store-view specific settings, such as service headers and analytics values.

The key of each overridden object must match the root folder path of the corresponding store view. These values merge into the default configuration.

{
  "public": {
    "default": {
      // default configuration
    },
    "/en/": {}, // inherits the default
    "/en-ca/": {
      "headers": {
        "all": {
          "Store": "en-ca"
        },
        "cs": {
          "Magento-Store-Code": "ca-store",
          "Magento-Website-Code": "base",
          "Magento-Store-View-Code": "en-ca"
        }
      },
      "analytics": {
        // overrides values from the default analytics configuration
      }
    },
    "/fr-ca/": {
      "headers": {
        "all": {
          "Store": "fr-ca"
        },
        "cs": {
          "Magento-Store-Code": "ca-store",
          "Magento-Website-Code": "base",
          "Magento-Store-View-Code": "fr-ca"
        }
      }
    }
  }
}

Headers configuration details:

• Magento-Store-Code: Must match the store code from the Commerce Admin
• Magento-Website-Code: Typically “base” for single-website setups
• Magento-Store-View-Code: Must match the store view code from the Admin

The analytics section contains the Adobe Commerce environment variables for the store view. These variables are used by the Analytics API. For more details, see Analytics.

Configuration Service

If you are using the Config Service, read the API documentation to learn how to publish your updates to the Config Service for your site.

Configure store switcher

Create a store-switcher file in each store view root folder containing a bulleted list. Each line must define the display name of your store with an active link to the store.

**Select a store:**

- Canada (CAD)
  - [Canada (EN)](https://main--aem-boilerplate-commerce--hlxsites.aem.page/en-ca/#nolocal)
  - [Canada (FR)](https://main--aem-boilerplate-commerce--hlxsites.aem.page/fr-ca/#nolocal)
- United States (USD)
  - [United States (USD)](https://main--aem-boilerplate-commerce--hlxsites.aem.page/en/#nolocal)

Important: The boilerplate automatically localizes internal links to keep users within their current locale (see Localizing links for technical details). To prevent automatic localization for links that point to a specific locale (such as store switcher links), add the hash #nolocal:

[United States (USD)](https://yoursite.com/en/#nolocal)

Best practice: Prioritize the current store view in the display order for better user experience. For example, in the en-ca folder’s store switcher, list “Canada (EN)” first.

Preview and validate content

To ensure proper functionality before publishing, test your new store views.

1. Push configuration changes to your storefront repository.

2. Return to the content files in both en-ca and fr-ca folders in da.live.

3. Preview content files:

   • Navigate to the en-ca folder
   • Open the index file
   • Click “Preview” to test the store view

4. Verify configuration in browser:

   • Check that the URL structure includes the store view path
   • Open browser Developer Tools
   • Navigate to Application → Session Storage
   • Look for the config key and expand the JSON object
   • Navigate to public → [your store path] → headers → cs
   • Verify the correct header values:
     • Magento-Store-Code
     • Magento-Website-Code
     • Magento-Store-View-Code
   • Open a product URL under each locale and confirm that a page is available with the intended sku metadata and localized product data

5. Test the store switcher:

   • Verify the store switcher correctly shows the current store view
   • Confirm customers can see and select other available stores
   • Check that switching stores navigates to the correct URLs

Session storage verification

Use session storage to verify configuration loads properly and identifies the correct store view.

Localize and translate content

After setting up infrastructure, prepare content for each locale.

1. Translate content files in the /en-ca/ and /fr-ca/ folders using the Localization (Document Authoring Tool) workflow.

2. Complete Commerce-specific tasks: Follow Commerce localization tasks to:

   • Translate drop-in placeholder files (cart.json, checkout.json, pdp.json)
   • Verify store view configuration aligns with folder structure
   • Test Commerce functionality across all locales

Final validation and publishing

Complete the implementation with thorough testing and team coordination.

1. Test all store views to ensure:

   • Proper URL structure
   • Correct content loading
   • Functional store switcher
   • Accurate header configuration
   • Proper currency and pricing display

2. Preview all files in the updated folders (/en-ca/, /fr-ca/) with AEM Sidekick .

3. Validate the storefront experience by accessing each new language/region and testing the rendering, navigation, and data accuracy.

4. Publish the store views:

   • Publish the updated folders using AEM Sidekick when ready
   • Update all store-switcher content documents to include links to the new store views

5. Prepare for marketing handoff:

   • Inform the marketing team that content folders are ready
   • Provide directory structure documentation
   • Share access to content folders for ongoing management

Success!

Your multistore infrastructure is now ready to support multiple locales with proper content management and customer experience.

Best practices

Folder structure

• Use clear, consistent naming conventions (en-ca, fr-ca)
• Ensure that folder names can be used in web URLs
• Match folder names exactly with the Adobe Commerce store view codes
• Maintain the same content structure across all store views

Configuration management

• Keep header values synchronized between config.json and Adobe Commerce Admin
• Document all store view codes and their corresponding folders
• Test configuration changes in preview before publishing
• Use version control for all configuration files

Content management

• Maintain separate content folders for each locale
• Use automated translation tools where possible
• Keep placeholder files synchronized across store views
• Test all localized content before publishing

Troubleshooting

Common Issues

Store View Not Loading

• Check product-page availability: For authored pages or BYOM, verify that each requested locale path has a published document or generated page with the correct sku metadata. See Provide product pages for each store view.
• For existing folder-mapped implementations only: Verify the locale-to-template mappings with GET https://admin.hlx.page/config/{ORG}/sites/{SITE}/folders.json. Make mapping changes through the Config Service API. Do not add mappings to fix missing authored or BYOM pages.
• Verify the headers: Ensure that the headers in config.json or Configuration Service match the store view codes in Adobe Commerce Admin
• Check the session storage: Use browser developer tools to verify that the correct headers are being sent

Content Not Displaying

• Verify the content structure: Ensure that all required files (index, store-switcher, placeholders) exist in the store view folder
• Check the file permissions: Verify that content files are properly published in da.live
• Validate the JSON syntax: Check that placeholder JSON files have valid syntax

Store Switcher Issues

• Check the links: Ensure that all store switcher links use the correct URLs and include #nolocal for absolute links
• Verify the file structure: Confirm that each store view has its own store-switcher file
• Test the navigation: Verify that switching between stores works correctly

Debugging Steps

1. Check the browser console for JavaScript errors
2. Verify the network requests in browser developer tools
3. Check the session storage for configuration values
4. Validate the configuration files for syntax errors
5. Test in different browsers to rule out browser-specific issues

Performance considerations

• Monitor site performance across all store views
• Optimize images and assets for each locale
• Consider CDN configuration for different regions
• Test loading times from the target markets

Related resources

• Content localization — Automated translation using da.live
• Storefront Configuration — Complete config.json reference
• Wishlist multistore support — Per-store-view wishlist data isolation
• Analytics — Analytics configuration for store views
• Store view configuration - Adobe Commerce Admin guide
• Folder mapping guidance and alternatives — For existing folder-mapped implementations only
• Config Service Setup - Configuration Service documentation
• Multi-Site Manager (MSM) — Share content between base and satellite sites
• Strategies for translation, localization, and rollout — Choose language and locale folders and plan content rollouts