Skip to content
Adobe Commerce Storefront

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 points to a different commerce backend or configuration, but shares the same code and content.
  2. Subfolders (Root Folders): 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, specifying which headers to send to the commerce backend, 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

Content is organized primarily by language. US English files should be placed in the en directory of the project root. All other language- and region-specific files should be placed in a directory that is named in the format language-code-region-code (using hyphens). For example, the /en/ directory contains data for the US market, while the /en-ca/ directory contains data for Canada. French content should be placed in directories with names like fr-fr for France and fr-ca for Canada.

  • 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.

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.

Merchant guidance: For translating placeholder files, see Commerce localization tasks.

Developer guidance: For technical implementation details, see Labeling and Localizing Drop-In Components.

Prerequisites

Before implementing multistore functionality, ensure you have:

Implementation walkthrough

This walkthrough demonstrates the complete process from initial planning to final validation, using a real-world scenario where the Acme brand expands 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. Check the fstab.yaml file in your repository to ensure it’s linked to the Document Authoring environment at da.live.

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

Create the content folder structure

Set up the folder structure in your Document Authoring environment to support the new store views.

  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. Copy content from the default root folder into each new store view folder:

    • Select all content from the /en/ folder
    • Copy the content
    • Navigate to the en-ca folder and paste
    • Repeat for the fr-ca folder

Configure Adobe Commerce store views

Create the corresponding store views in Adobe Commerce Admin to match your content folder structure.

  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)

Update folder mapping

Product Detail Pages (PDP) are mapped to a single document at products/default. When adding a new store view, you’ll need to add a corresponding folder mapping for the new URLs.

Using fstab.yaml

If your project uses a fstab.yaml file, add the new store view mapping under the folders: section:

mountpoints:
  /: https://example.mountpoint.com/:f:/r/sites/myproject


folders:
  /en/products/: /en/products/default
  /en-ca/products/: /en-ca/products/default
  /fr-ca/products/: /fr-ca/products/default

Using Configuration Service

If your project uses the Configuration Service, update the configuration to add the new store view mapping under the folders: section:

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

To learn more about the Config Service, see aem.live’s documentation or read the API documentation to learn how to publish your updates.

Update site configuration

You must update your storefront config to include configuration overrides for the new store view. 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 will be merged 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.

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). For links that should always point to a specific locale (such as store switcher links), add the hash #nolocal to prevent automatic localization:

[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

Test your new store views to ensure proper functionality before publishing.

  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

  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

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 your chosen authoring tool:

  2. Complete Commerce-specific tasks: Follow the Commerce localization tasks guide 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

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 the folder mapping: Verify that the folder mapping in fstab.yaml or the Configuration Service matches your folder structure
  • Verify the headers: Ensure that the headers in config.json 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