Storefront configuration

Connect your storefront to the intended Commerce environment and confirm that the browser loads the right settings. The storefront configurationThe JSON configuration object used by storefront code to resolve endpoints, headers, analytics, and plugin behavior. contains the API addresses, store or catalog context, and other values that Commerce blocks and drop-ins use.

For a new project, follow the connection task below. If Site Creator or your team already configured the project, start with Confirm the loaded configuration instead of replacing working settings.

Connect your storefront to Commerce

Before changing settings, confirm your backend requirements in Backend options. Work with the Commerce administrator or integration owner to gather:

• The approved development environment and the site or local preview where you will test it.
• The GraphQL API address for catalog requests.
• The API address for cart, checkout, and account operations, when those features are required.
• The store or catalog header values that identify the correct data.
• A known product and its expected price and currency.

Adobe Commerce as a Cloud Service supports catalog and transactional operations. With Adobe Commerce Optimizer, the existing commerce platform still handles transactions. The generator output does not replace a required third-party cart or checkout integration.

Keep secret credentials out of storefront settings

The storefront loads these settings in the shopper’s browser. Do not include passwords, private API keys, or secret integration credentials in browser-delivered configuration.

Generate and save a configuration using the values approved for your project:

1. Open the config generator tool .

2. Enter the approved GraphQL API URL in GraphQL API Endpoint.

3. Select Generate.

   The tool returns a JSON configuration for the detected environment. Generation alone does not prove that all required connections work.

4. Compare the generated values with the approved connection details.

   Use Endpoints and Headers to check the backend-specific fields. Replace sample default valuesStarter values in a sample configuration that must be replaced with environment-specific values for your project. and any remaining placeholders.

5. Select Copy.

6. Save the approved configuration in your project’s configuration source.

   For shared site configuration, follow Setting up the configuration service and its public configuration reference . For local or feature-branch testing, use a config.json file at the storefront repository root. Coordinate changes to a shared site with its owner.

A repository config.json takes precedence over the site’s public configuration. Use the Configuration Service for normal production setup. Keep local and test overrides out of the production branch. An intentional repository-based production configuration is an advanced exception.

Confirm the loaded configuration

Check the same local or preview origin where you will test the storefront. An origin is the address before the page path. The browser can retain an older configuration in session storage even after the source changes.

1. Open /config.json on that origin in your browser.

   The response should contain JSON with the intended endpoints and store or catalog values. If it is missing or incorrect, check the configuration source and code branch before continuing.

2. Open Application > Session Storage in your browser’s developer tools.

   Select the storage for the storefront origin. These panel names apply to Chrome and Edge.

3. Delete only the config entry.

4. Reload the storefront page.

5. Inspect the recreated config entry in session storage.

   Confirm that the loaded endpoints and store or catalog context match the approved settings. If values are still old, compare them with the /config.json response and investigate the source or delivery cache.

Matching settings confirm that configuration loaded, not that every shopping feature works. Continue with Verify your storefront setup to test content, product data, and the required shopping features.

The reference sections below retain the settings for endpoints, headers, analytics, plugins, and multistore projects. They also describe helper APIs such as getConfigValue functionHelper function that reads a configuration value by dot-notation path from storefront config data. and getHeaders functionHelper function that returns a header map for a given storefront scope based on configured header entries..

Configuration Caching

Storefront configuration can be cached separately in network responses and browser session storage.

• Response caching: Browsers and CDNs can reuse an earlier configuration response. Refresh behavior depends on the response’s Cache-Control header and the site’s cache settings.

• Browser session storage: The storefront stores configuration in session storage with a two-hour expiry. On a later configuration load, it fetches the configuration again if the cached entry is missing or expired. To test a change sooner, follow Confirm the loaded configuration.

Deleting the config entry clears only session storage. It does not clear cached network responses in the browser or CDN. If /config.json still returns old values, check the configuration source, code branch, and cache settings with the site owner.

Configuration Sections

The following sections detail each part of your configuration for Adobe Commerce. Each section includes placeholders (marked with {{PLACEHOLDER}}) that you must replace with your specific Commerce environment details.

You can find your configuration in your code repo at /config.json, or in the config service for your site. If you do not have a configuration yet, you can:

• Copy and customize the demo config for the boilerplate: https://main--aem-boilerplate-commerce--hlxsites.aem.live/config.json .
• Or use the Config Generator tool to generate a configuration with your backend values (contains placeholders to fill in).

Be sure to update all values to match your Commerce backend before deploying.

Endpoints

The endpoints properties define the GraphQL API endpoints for your Commerce backend.

{
  "commerce-core-endpoint": "{{COMMERCE_CORE_ENDPOINT}}",
  "commerce-endpoint": "{{COMMERCE_ENDPOINT}}"
}

Configuration Properties:

• commerce-core-endpoint (read/write) — Core GraphQL endpoint for queries and mutations. This endpoint handles all write operations and some read operations. See Adobe Commerce GraphQL API for details.

• commerce-endpoint (read-only) — Services GraphQL endpoint optimized for read-only operations with Catalog Service, Live Search, and Product Recommendations. It is also optimized for performance for product data retrieval. For details, see the following documentation:

  • For Adobe Commerce as a Cloud Service, see the Catalog Service Guide .
  • For Adobe Commerce Optimizer, see the Merchandising Services Developer Guide .

Headers

The headers section defines HTTP headers required for API authentication and store context. Headers are organized by scope to apply different authentication and context settings for different request types. The specific headers required depend on your Commerce environment type.

Adobe Commerce (PaaS)

Adobe Commerce PaaS environments use standard Adobe Commerce header naming conventions and require API keys for SaaS services.

{
  "headers": {
    "all": {
      "Store": "{{STORE_VIEW_CODE}}"
    },
    "cs": {
      "Magento-Store-Code": "{{STORE_CODE}}",
      "Magento-Store-View-Code": "{{STORE_VIEW_CODE}}",
      "Magento-Website-Code": "{{WEBSITE_CODE}}",
      "x-api-key": "{{API_KEY}}",
      "Magento-Environment-Id": "{{ENVIRONMENT_ID}}"
    }
  }
}

Header Scopes:

• all - Headers applied to all GraphQL requests

  • Store - Store view code for Core GraphQL requests. See GraphQL Headers for details.

• cs - Headers for Catalog Service requests

  • Magento-Store-Code - Store to connect to. See Create stores for details.
  • Magento-Store-View-Code - Store view for Catalog Service requests. See Store views for details.
  • Magento-Website-Code - Website to connect to. See Create websites for details.
  • x-api-key - API key for SaaS services (Catalog Service, Live Search, Product Recommendations). See Commerce Services Connector for details.
  • Magento-Environment-Id - Connects the storefront to the cloud instance serving it. See Cloud Environment overview for details.

Adobe Commerce as a Cloud Service (ACCS)

Adobe Commerce as a Cloud Service uses standard Adobe Commerce header naming conventions but does not require API keys or environment IDs in the default configuration.

{
  "headers": {
    "all": {
      "Store": "{{STORE_VIEW_CODE}}"
    },
    "cs": {
      "Magento-Store-Code": "{{STORE_CODE}}",
      "Magento-Store-View-Code": "{{STORE_VIEW_CODE}}",
      "Magento-Website-Code": "{{WEBSITE_CODE}}"
    }
  }
}

Header Scopes:

• all - Headers applied to all GraphQL requests

  • Store - Store view code for Core GraphQL requests. See GraphQL Headers for details.

• cs - Headers for Catalog Service requests

  • Magento-Store-Code - Store to connect to. See Create stores for details.
  • Magento-Store-View-Code - Store view for Catalog Service requests. See Store views for details.
  • Magento-Website-Code - Website to connect to. See Create websites for details.

Adobe Commerce Optimizer

Adobe Commerce Optimizer uses different header naming conventions and requires Commerce Optimizer-specific headers as defined in the Merchandising Services API documentation .

{
  "headers": {
    "cs": {
      "AC-View-ID": "{{CATALOG_VIEW_ID}}",
      "AC-Price-Book-ID": "{{PRICE_BOOK_ID}}",
      "AC-Policy-{{*}}": "{{ATTRIBUTE_VALUE}}"
    }
  }
}

Header Scopes:

• cs - Headers applied to all GraphQL requests
  • AC-View-ID - (Required) The unique ID assigned to the catalog view that products will be sold through. You can find this in the Adobe Commerce Optimizer UI .
  • AC-Policy-{{*}} - (Optional) Policy trigger for filtering products by attribute. The header should match the “name” of the trigger. For example, AC-Policy-Brand:Cruz for brand filtering using “Cruz”. You can specify multiple policy headers per request.
  • AC-Price-Book-ID - (Optional) Specifies the Price Book ID to use for pricing. Each catalog view defines a default Price Book. If a customer has an assigned Price Book, it is used when it falls within the allowed Price Books for the catalog view. Otherwise, the default Price Book for the catalog view is used. See Price Book ID setup for implementation details.

Analytics

The analytics section contains store and environment metadata for tracking and reporting. The specific values depend on your Commerce environment type.

Adobe Commerce (PaaS) / SaaS

For Adobe Commerce PaaS and Adobe Commerce as a Cloud Service environments, use standard Commerce store and website identifiers from your Commerce Environment. You can obtain these values using a storeConfig query.

{
  "analytics": {
    "aep-ims-org-id": "{{IMS_ORG_ID}}",
    "aep-datastream-id": "{{DATASTREAM_ID}}",
    "base-currency-code": "{{CURRENCY_CODE}}",
    "environment": "{{ENVIRONMENT_TYPE}}",
    "environment-id": "{{ENVIRONMENT_ID}}",
    "store-code": "{{STORE_CODE}}",
    "store-id": {{STORE_ID}},
    "store-name": "{{STORE_NAME}}",
    "store-url": "{{STORE_URL}}",
    "store-view-code": "{{STORE_VIEW_CODE}}",
    "store-view-id": {{STORE_VIEW_ID}},
    "store-view-name": "{{STORE_VIEW_NAME}}",
    "website-code": "{{WEBSITE_CODE}}",
    "website-id": {{WEBSITE_ID}},
    "website-name": "{{WEBSITE_NAME}}"
  }
}

Configuration Properties:

• aep-ims-org-id - (Optional) Adobe IMS Organization ID for Experience Platform integration (for example, "1234567890ABCDEF7F000101@AdobeOrg")
• aep-datastream-id - (Optional) Datastream ID for routing data to Adobe Experience Platform (for example, "12345678-1234-1234-1234-123456789012")
• base-currency-code - The base currency code for the store (for example, “USD,” “EUR”)
• environment - Environment type (“Production”, “Testing”)
• environment-id - Unique identifier for the Commerce environment
• store-url - Base URL for the store
• store-code - Code identifier for the store from your Commerce environment
• store-id - Numeric ID for the store
• store-name - Display name for the store
• store-view-code - Code identifier for the store view
• store-view-id - Numeric ID for the store view
• store-view-name - Display name for the store view
• website-code - Code identifier for the website from your Commerce environment
• website-id - Numeric ID for the website
• website-name - Display name for the website

Adobe Experience Platform integration

To enable automatic event forwarding to Adobe Experience Platform, include both aep-ims-org-id and aep-datastream-id in your analytics configuration. When both values are present, events will automatically be sent to AEP. See the Adobe Experience Platform integration guide for detailed setup instructions.

Adobe Commerce Optimizer

For Adobe Commerce Optimizer environments, use a simplified analytics configuration structure:

{
  "analytics": {
    "aep-ims-org-id": "{{IMS_ORG_ID}}",
    "aep-datastream-id": "{{DATASTREAM_ID}}",
    "base-currency-code": "{{CURRENCY_CODE}}",
    "environment": "{{ENVIRONMENT_TYPE}}",
    "environment-id": "{{YOUR_TENANT_ID}}",
    "store-url": "{{STORE_URL}}",
    "store-view-currency-code": "{{CURRENCY_CODE}}",
    "storefront-template": "{{TEMPLATE_TYPE}}",
    "view-id": "{{CATALOG_VIEW_ID}}"
  }
}

Configuration Properties:

• aep-ims-org-id - (Optional) Adobe IMS Organization ID for Experience Platform integration (for example, "1234567890ABCDEF7F000101@AdobeOrg")
• aep-datastream-id - (Optional) Datastream ID for routing data to Adobe Experience Platform (for example, "12345678-1234-1234-1234-123456789012")
• base-currency-code - The base currency code for the store (for example, “USD”, “EUR”)
• environment - Environment type (“Production”, “Testing”)
• environment-id - The tenant ID for the Adobe Commerce Optimizer instance
• store-url - Base URL for the store
• store-view-currency-code - Currency code for the store view (for example, “USD”, “EUR”)
• storefront-template - (Optional) Storefront template type (for example, “Other”)
• view-id - The unique ID assigned to the catalog view from the Adobe Commerce Optimizer UI

Plugins

The plugins section configures various Commerce plugins and features.

{
  "plugins": {
    "picker": {
      "rootCategory": "{{ROOT_CATEGORY_ID}}"
    }
  }
}

Configuration Properties:

• picker.rootCategory - Root category ID for the product picker. This determines which category serves as the starting point when browsing products in the Commerce interface.

Multistore

The multistore section manages configurations for multiple store views and internationalization. This allows different configurations for different locales or store views. Each non-”default” configuration merges with the default at runtime and applies to the corresponding locale or store view. For example, the below serves as a foundation for configuration for the site at aemshop.net/fr.

{
  "/fr/": {
    "headers": {
      "all": {
        "Store": "{{FRENCH_STORE_VIEW_CODE}}"
      },
      "cs": {
        "Magento-Store-Code": "{{FRENCH_STORE_CODE}}",
        "Magento-Website-Code": "{{FRENCH_WEBSITE_CODE}}",
        "Magento-Store-View-Code": "{{FRENCH_STORE_VIEW_CODE}}"
      }
    }
  }
}

Configuration Properties:

• Path-based configuration - Use URL paths (like /fr/, /de/, etc.) to define locale-specific or store-specific overrides
• Header overrides - Override default headers for specific store views
• Store context - Define different store, website, and store view codes for each locale

For content paths and store view setup, see Multistore setup.

Additional Configuration Options

Some configuration options can be set to enable or disable certain boilerplate features.

{
  "commerce-assets-enabled": boolean,
  "commerce-b2b-enabled": boolean,
  "commerce-companies-enabled": boolean,
}

• commerce-assets-enabled - Boolean flag to enable or disable AEM Assets within the storefront
• commerce-b2b-enabled - Boolean flag to enable or disable B2B-related global and shared logic within the storefront. When enabled, this flag is passed to the Auth initializer as customerPermissionRoles: true to enable customer role permissions API. This flag controls B2B functionality at the authentication and authorization level, enabling the drop-in to fetch B2B customer role permissions automatically on initialization and re-fetch when authentication state changes. See the User Auth initialization documentation for details.
• commerce-companies-enabled - Boolean flag to enable or disable Commerce B2B company features within the storefront. This flag controls company-specific features such as company management, company structure, and company-related blocks.

B2B Configuration Flags

Understanding the difference:

• commerce-b2b-enabled - Controls B2B functionality at the authentication and authorization level. When set to true, this flag enables the customer role permissions API in the Auth drop-in (via the customerPermissionRoles parameter), which automatically fetches B2B customer role permissions including purchase order and company management capabilities. This configuration is required for B2B features to work properly. See the User Authentication changelog for implementation details.

• commerce-companies-enabled - Controls company-specific features and blocks. This flag enables or disables company management features, company structure, and company-related commerce blocks.

Relationship: commerce-b2b-enabled is required for B2B features as it enables the authentication system. commerce-companies-enabled controls company features, which require commerce-b2b-enabled to be true.

For a complete B2B storefront with company features, set both flags to true:

{
  "commerce-b2b-enabled": true,
  "commerce-companies-enabled": true
}

Implementation: To use commerce-b2b-enabled in your storefront, read it from config in your Auth initializer and pass it to the Auth drop-in:

scripts/initializers/user-auth.js

import { initializers } from '/@dropins/tools/initializer.js';
import { initialize } from '@dropins/storefront-auth';
import { getConfigValue } from '/scripts/configs.js';

const isB2BEnabled = await getConfigValue('commerce-b2b-enabled');

await initializers.mountImmediately(initialize, {
  customerPermissionRoles: isB2BEnabled,
  // ... other options
});

This enables the customer role permissions API when B2B features are enabled in your configuration.

Configuration Examples

The following examples show real config.json files from different Adobe Commerce environments. These examples demonstrate the actual structure and values used in production environments.

Adobe Commerce (PaaS)

This example shows the configuration for an Adobe Commerce PaaS environment, which includes additional features like multistore support and asset management. This configuration is used on this site: https://www.aemshop.net/

aemshop.net config.json example

{
  "public": {
    "default": {
      "commerce-core-endpoint": "https://www.aemshop.net/graphql",
      "commerce-endpoint": "https://www.aemshop.net/cs-graphql",
      "headers": {
        "all": {
          "Store": "default"
        },
        "cs": {
          "Magento-Store-Code": "main_website_store",
          "Magento-Store-View-Code": "default",
          "Magento-Website-Code": "base",
          "x-api-key": "4dfa19c9fe6f4cccade55cc5b3da94f7",
          "Magento-Environment-Id": "f38a0de0-764b-41fa-bd2c-5bc2f3c7b39a"
        }
      },
      "analytics": {
        "aep-ims-org-id": null,
        "aep-datastream-id": null,
        "base-currency-code": "USD",
        "environment": "Production",
        "environment-id": "f38a0de0-764b-41fa-bd2c-5bc2f3c7b39a",
        "store-code": "main_website_store",
        "store-id": 1,
        "store-name": "Main Website Store",
        "store-url": "https://www.aemshop.net",
        "store-view-code": "default",
        "store-view-id": 1,
        "store-view-name": "Default Store View",
        "website-code": "base",
        "website-id": 1,
        "website-name": "Main Website"
      },
      "plugins": {
        "picker": {
          "rootCategory": "2"
        }
      },
      "commerce-assets-enabled": false
    },
    "/fr/": {
      "headers": {
        "all": {
          "Store": "fr"
        },
        "cs": {
          "Magento-Store-Code": "fr_store",
          "Magento-Website-Code": "fr_website",
          "Magento-Store-View-Code": "fr"
        }
      }
    }
  }
}

Adobe Commerce as a Cloud Service (ACCS)

This example shows the configuration for Adobe Commerce as a Cloud Service (ACCS). For ACCS you only need to set commerce-endpoint to your ACCS GraphQL URL; the same endpoint is used for catalog and core. This configuration is used on this site: https://main—boilerplate-accs—adobe-commerce.aem.live/

ACCS config.json

{
  "public": {
    "default": {
      "commerce-endpoint": "https://na1-sandbox.api.commerce.adobe.com/LwndYQs37CvkUQk9WEmNkz/graphql",
      "headers": {
        "all": {
          "Store": "default"
        },
        "cs": {
          "Magento-Store-Code": "main_website_store",
          "Magento-Store-View-Code": "default",
          "Magento-Website-Code": "base"
        }
      },
      "analytics": {
        "base-currency-code": "USD",
        "environment": "Testing",
        "environment-id": "LwndYQs37CvkUQk9WEmNkz",
        "store-code": "main_website_store",
        "store-id": 1,
        "store-name": "ACCS Store",
        "store-url": "https://main--boilerplate-accs--adobe-commerce.aem.live",
        "store-view-code": "default",
        "store-view-id": 1,
        "store-view-name": "Default Store View",
        "website-code": "base",
        "website-id": 1,
        "website-name": "Main Website"
      },
      "plugins": {
        "picker": {
          "rootCategory": "2"
        }
      }
    }
  }
}

Adobe Commerce Optimizer (ACO)

This example shows the configuration for Adobe Commerce Optimizer (ACO), which uses different header naming conventions and includes ACO-specific settings. For ACO, set commerce-endpoint (ACO GraphQL URL for catalog) at a minimum. Set commerce-core-endpoint (your core endpoint—PaaS or your own Adobe Commerce hosted environment) to enable transactional or other core-related functionality. Include “adobe-commerce-optimizer”: true. This example is from https://main—boilerplate-aco—adobe-commerce.aem.live/ and does not include a core endpoint.

ACO config.json

{
  "public": {
    "default": {
      "adobe-commerce-optimizer": true,
      "commerce-endpoint": "https://na1-sandbox.api.commerce.adobe.com/8idEEDDiVwjCEJAyB5kjfi/graphql",
      "headers": {
        "cs": {
          "ac-view-id": "0d3eebf7-b5fb-4904-9ccf-f35fcc61862b",
          "ac-price-book-id": "west_coast_inc"
        }
      },
      "analytics": {
        "base-currency-code": "USD",
        "environment": "Testing",
        "environment-id": "8idEEDDiVwjCEJAyB5kjfi",
        "store-url": "https://main--boilerplate-aco--adobe-commerce.aem.live/",
        "store-view-currency-code": "USD",
        "storefront-template": "Other",
        "view-id": "0d3eebf7-b5fb-4904-9ccf-f35fcc61862b"
      },
      "plugins": {
        "picker": {
          "rootCategory": "2"
        }
      }
    }
  }
}

Local development

Use local or feature-branch overrides to test a different Commerce environment without changing the shared site settings. Generate and save new values with Connect your storefront to Commerce. The guidance here explains where those overrides apply.

How configuration resolution works

The browser requests /config.json from the storefront origin:

• A config.json file served from the repository root takes precedence.
• Without that file, Edge Delivery Services serves the site’s public configuration from the Configuration Service.

Keep test overrides out of production

A local or test configuration committed to the production branch overrides the shared settings for that storefront. For normal production setup, use the Configuration Service and keep the repository override out of that branch, typically main.

Getting a starter configuration

• For a new connection, follow the generator and save steps in Connect your storefront to Commerce.
• For an existing project, review its approved settings before generating a replacement.
• For an example of the JSON structure, inspect the reference storefront configuration . Its environment and values are not a substitute for your own backend settings.

Local development configuration

Save a development-only config.json at the storefront repository root when testing a local override. Use the approved endpoints, headers, analytics settings, and other values for that environment.

For a personal override, use the project’s agreed ignore rules to keep an untracked file out of commits. Ignore rules do not stop Git from tracking a file that was already committed. Review the repository changes before committing so a local environment does not become the shared configuration.

From the storefront repository root, you can exclude a personal config.json without changing the shared .gitignore:

# Add the root configuration file to this checkout's local Git exclusions.
printf '\n/config.json\n' >> "$(git rev-parse --git-path info/exclude)"
git check-ignore -v config.json

The last command should show the /config.json rule and the local exclude file that contains it. This applies only to an untracked personal override, not a configuration that the team intentionally tracks.

Branch-based configuration

Choose the configuration source that matches the environment you intend to change.

Feature-branch override

A config.json committed only to a feature or test branch overrides public configuration on that branch’s preview. Open the intended branch preview URL when checking it. Do not merge the test override into the production branch.

Shared public configuration

Use the Configuration Service for normal production setup. Its public configuration is available through https://admin.hlx.page/config/{ORG}/sites/{SITE}/public.json, where {ORG} and {SITE} are your Edge Delivery organization and site names. This updates shared settings without a code deployment.

Keep a repository config.json out of the production branch so these public values can be served.

Production repository override (advanced)

A team can intentionally manage production configuration in the repository instead. A root config.json on the production branch takes precedence over public configuration, so changes to the Configuration Service will not replace it.

Use this exception only when the project owner has chosen repository-based production configuration. Review the file as production settings, not as a temporary development override.

Testing configuration changes

Save or deploy the change to its intended source, then follow Confirm the loaded configuration. That procedure checks both the delivered /config.json response and the configuration retained by the browser.

If the values remain old, use Configuration caching to distinguish delivery caching from session storage. Reloading or deleting the session-storage entry does not by itself invalidate a cached network response.

Production Configuration Templates

Beyond config.json, the boilerplate includes template configuration files with placeholders for the rest of your production site setup.

default-site.json

Comprehensive site configuration template for production deployment:

{
  "version": 1,
  "code": {
    "owner": "{ORG}",
    "repo": "{REPO}",
    "source": {
      "type": "github",
      "url": "https://github.com/{ORG}/{REPO}"
    }
  },
  "content": {
    "source": {
      "url": "{CONTENT_SOURCE}",
      "type": "onedrive"
    }
  },
  "folders": {
    "/products/": "/products/default"
  },
  "cdn": {
    "live": {
      "host": "main--{SITE}--{ORG}.aem.live"
    },
    "preview": {
      "host": "main--{SITE}--{ORG}.aem.page"
    }
  },
  "headers": {},
  "public": {
    "default": {
      "commerce-core-endpoint": "{ENDPOINT}",
      "commerce-endpoint": "{CATALOG_ENDPOINT}",
      "headers": {
        "all": {
          "Store": "default"
        },
        "cs": {
          "Magento-Store-Code": "{STORE_CODE}",
          "Magento-Store-View-Code": "{STORE_VIEW_CODE}",
          "Magento-Website-Code": "{WEBSITE_CODE}",
          "x-api-key": "{COMMERCE_API_KEY}",
          "Magento-Environment-Id": "{COMMERCE_ENVIRONMENT_ID}"
        }
      },
      "analytics": {
        "aep-ims-org-id": "{IMS_ORG_ID}",
        "aep-datastream-id": "{DATASTREAM_ID}",
        "base-currency-code": "USD",
        "environment": "Production",
        "store-id": "{STORE_ID}",
        "store-name": "Main Website Store",
        "store-url": "{DOMAIN}",
        "store-view-id": "{STORE_VIEW_ID}",
        "store-view-name": "Default Store View",
        "website-id": "{WEBSITE_ID}",
        "website-name": "Main Website"
      },
      "plugins": {
        "picker": {
          "rootCategory": "{YOUR_ROOT_CATEGORY_ID}"
        }
      }
    }
  },
  "robots": {
    "txt": "User-agent: *\nAllow: /\nDisallow: /drafts/\nDisallow: /enrichment/\nDisallow: /tools/\nDisallow: /plugins/experimentation/\n\nSitemap: https://{DOMAIN}/sitemap-index.xml"
  },
  "access": {
    "admin": {
      "role": {
        "config_admin": ["{ADMIN_USER_EMAIL}"]
      },
      "requireAuth": "auto"
    }
  }
}

Replace the {PLACEHOLDER} values with your actual configuration.

default-query.yaml

Content indexing configuration for generating sitemap and enrichment data:

version: 1
indices:
  sitemap:
    target: /sitemap.json
    exclude:
      - 'drafts/**'
      - 'enrichment/**'
      - 'fragments/**'
      - 'products/**'
    properties:
      title:
        select: head > meta[property="og:title"]
        value: |
          attribute(el, 'content')
      image:
        select: head > meta[property="og:image"]
        value: |
          attribute(el, 'content')
      description:
        select: head > meta[name="description"]
        value: |
          attribute(el, 'content')
      template:
        select: head > meta[name="template"]
        value: |
          attribute(el, 'content')
      robots:
        select: head > meta[name="robots"]
        value: |
          attribute(el, 'content')
      lastModified:
        select: none
        value: parseTimestamp(headers["last-modified"], "ddd, DD MMM YYYY hh:mm:ss GMT")
  enrichment:
    target: /enrichment/enrichment.json
    include:
      - '**/enrichment/**'
    properties:
      title:
        select: head > meta[property="og:title"]
        value: |
          attribute(el, 'content')
      products:
        select: head > meta[name="enrichment-products"]
        values: |
          match(attribute(el, 'content'), '([^,]+)')
      categories:
        select: head > meta[name="enrichment-categories"]
        values: |
          match(attribute(el, 'content'), '([^,]+)')
      positions:
        select: head > meta[name="enrichment-positions"]
        values: |
          match(attribute(el, 'content'), '([^,]+)')

default-sitemap.yaml

Sitemap generation configuration:

sitemaps:
  default:
    source: /sitemap.json
    destination: /sitemap-content.xml
    lastmod: YYYY-MM-DD

The sitemap reads from the generated sitemap.json (created by default-query.yaml) and outputs an XML sitemap.

Read configuration in custom code

Use the SDK configuration helpers when you build custom block code beyond the included shopping features. The current storefront initializes configuration before loading its block decorators. These helpers read the values already selected for the current page; they do not fetch or initialize configuration themselves.

The example below is a new diagnostic block for local development, not a replacement for an included Commerce block. Follow Create commerce blocks to add its files and a matching block to a content page.

Import the configuration functions

Import getConfigValue and getHeaders from the SDK. Do not create a scripts/configs.js file or reinitialize configuration in each block.

blocks/config-check/config-check.js (new example block)

import { getConfigValue, getHeaders } from '/@dropins/tools/lib/aem/configs.js';

export default function decorate(block) {
// Storefront startup has already resolved the configuration for this page.
const catalogEndpoint = getConfigValue('commerce-endpoint');
if (typeof catalogEndpoint !== 'string' || !catalogEndpoint) {
  throw new Error('The commerce-endpoint configuration value is missing.');
}

const coreEndpoint = getConfigValue('commerce-core-endpoint') || catalogEndpoint;
const catalogHeaders = getHeaders('cs');

console.table({
  catalogEndpoint,
  coreEndpoint,
  analyticsCurrency: getConfigValue('analytics.base-currency-code'),
  rootCategory: getConfigValue('plugins.picker.rootCategory'),
});

// Inspect header names without printing their values.
console.info('Configured catalog header names:', Object.keys(catalogHeaders));

const message = document.createElement('p');
message.textContent = 'Storefront configuration is available. Check the browser console for its values.';
block.replaceChildren(message);
}

Open the local page containing the new block. It should display the message and print a table in the browser console. Compare the endpoint values with the approved environment. Optional analytics or plugin values can be undefined when the project does not configure them.

This example confirms that custom code can read configuration. It does not prove that a Commerce request succeeds. Use Verify your storefront setup to test the actual content, catalog, and shopping features.

If the SDK reports that configuration is not initialized, confirm that the page uses the storefront’s normal startup flow. Do not hide the error by adding a second configuration loader.

Access endpoint configuration

getConfigValue('commerce-endpoint') reads the catalog endpoint. The core endpoint is commerce-core-endpoint; the starter uses the catalog endpoint as its fallback when no separate core endpoint is configured. The example uses the same fallback.

The helpers return resolved values synchronously after initialization, so these calls do not need await.

Access header configuration

getHeaders('cs') combines the common headers.all values with the catalog-specific headers.cs values. The scoped values take precedence when the same header appears in both. getHeaders('all') reads the common headers.

These helpers read configured headers, not every header that a running shopping feature adds. For example, customer context can change after sign-in.

Access analytics and other configuration

getConfigValue also accepts dot-separated paths such as analytics.store-url, analytics.base-currency-code, analytics.environment, and plugins.picker.rootCategory. Use the path for the setting your custom code actually needs.

The helper reads configuration; it does not send analytics events or enable a plugin. Follow the feature’s setup instructions for those behaviors.

Make API requests with configuration

For custom Commerce requests, reuse the starter’s configured clients in scripts/commerce.js: CS_FETCH_GRAPHQL for catalog requests and CORE_FETCH_GRAPHQL for core Commerce operations. They connect the resolved endpoint and headers to the running storefront’s customer context.

Use a query supported by the selected backend. Adobe Commerce Optimizer exposes the Merchandising API ; Adobe Commerce transactional operations use core GraphQL . A query written for one API is not automatically valid for the other.

For an Adobe Commerce core GraphQL connection, add this separate local development block to read the configured store’s code and base currency. The storeConfig query is not an Adobe Commerce Optimizer merchandising query.

blocks/config-request/config-request.js (new example block)

import { CORE_FETCH_GRAPHQL } from '/scripts/commerce.js';

export default async function decorate(block) {
// Reuse the endpoint and headers selected during storefront startup.
const { data, errors } = await CORE_FETCH_GRAPHQL.fetchGraphQl(`
  query StorefrontConnectionCheck {
    storeConfig {
      store_code
      base_currency_code
    }
  }
`);

if (errors?.length) {
  throw new Error(errors.map(({ message }) => message).join('; '));
}

const store = data?.storeConfig;
if (!store?.store_code || !store.base_currency_code) {
  throw new Error('The storeConfig query did not return a store code and base currency.');
}

const result = document.createElement('p');
result.textContent = `Store: ${store.store_code}; base currency: ${store.base_currency_code}`;
block.replaceChildren(result);
}

Add a matching config-request block to a local content page, as described in Create commerce blocks. A successful response displays a message such as Store: default; base currency: USD. Compare both values with the intended environment.

fetchGraphQl returns GraphQL errors alongside any response data, so the example checks those errors before displaying a result. If the query fails, confirm that the configured core endpoint supports storeConfig and that its headers select the intended store.

Configure a drop-in initializer

The standard Commerce blocks already load their drop-in initializers. The included cart initializer sets the cart’s core API client and loads its text labels before initialization.

The cart block already imports this initializer before rendering. Inside initializeDropin, the initializer:

• Calls setEndpoint(CORE_FETCH_GRAPHQL) to connect the cart to the configured core client.
• Loads placeholders/cart.json with fetchPlaceholders and places the labels in langDefinitions.default.
• Passes the cart’s initialize function and an options object containing langDefinitions and the existing feature settings to initializers.mountImmediately.

When customizing this flow, edit the existing initializer and preserve its feature settings. Do not replace it with either diagnostic block above or add a second cart initialization.

Summary

The Storefront configuration provides a structured approach to connecting your storefront to Adobe Commerce backends. By organizing settings into clear sections for endpoints, headers, analytics, plugins, and multistore configurations, you can easily customize your storefront for different Commerce environments. The configuration system supports Adobe Commerce (PaaS), Adobe Commerce as a Cloud Service (SaaS), and Adobe Commerce Optimizer, each with specific header requirements and authentication methods. For local development and testing, use a config.json file in your repository or the Configuration Service public config, as repository files take precedence. Use the getConfigValue and getHeaders helper functions to access these settings in your Commerce blocks, ensuring consistent and maintainable integration with your Commerce backend.