Realm Setup

Take a new sandbox or realm from an empty instance to a working storefront with the B2C CLI and your AI assistant. Load a sample site from the storefront datasets, rebuild search indexes, set up a Storefront Next storefront, and replicate from staging to production.

The b2c-setup skill guides your assistant through these steps. The B2C MCP features it, and the b2c-cli plugin includes it.

Before You Start

• Configure each instance: see Configuration. For a realm, add a named instance for staging, production, and any development instance.
• Use an API client with access to every instance. See Account Manager and Authentication.
• Check the setup with b2c setup inspect -i <instance>.

Protect Shared Instances

Staging, production, and development are shared instances. A site import there can change global settings, such as active locales and the instance time zone, for every site. Production and development get code and data from staging by replication; do not import site data on them directly.

Add a Safety Mode policy to each shared instance. With confirm: true, the CLI asks before an action the safety level blocks:

{
  "configs": [
    {
      "name": "sandbox",
      "hostname": "abcd-001.dx.commercecloud.salesforce.com",
      "safety": {"level": "NONE"}
    },
    {
      "name": "staging",
      "hostname": "staging-abcd-example.demandware.net",
      "safety": {"level": "NO_DELETE", "confirm": true}
    },
    {
      "name": "production",
      "hostname": "production-abcd-example.demandware.net",
      "safety": {"level": "READ_ONLY", "confirm": true}
    }
  ]
}

See per-instance policies and confirmation. The b2c-setup skill also tells your assistant to name the target instance and wait for your approval before each change to a shared instance.

Storefront Datasets

Salesforce publishes sample data for the reference storefronts in storefront-datasets. Each dataset is a site archive with a site, catalogs, price books, inventory, content, and promotions.

The repository is available to Commerce Cloud customers and partners. To get access, link your GitHub account through Account Manager; see Salesforce Commerce Cloud GitHub Repositories and Access. Without access, GitHub shows a 404 page for the repository.

Dataset directory	Site ID
foundations-data	Foundations
marketstreet	MarketStreet
beautynext	BeautyNext
footwear-data	Footwear
furniture-data	Furniture
luxury-data	Luxury

Releases are tagged with the Storefront Next template version they target, such as v1.4.0. Use the release that matches your storefront's template. Each release also attaches a ZIP per dataset.

git clone --branch v1.4.0 --depth 1 https://github.com/SalesforceCommerceCloud/storefront-datasets.git

b2c job import accepts a directory, so you do not need to zip a dataset first. Add --split if the upload is too large for one import. On an instance that already has sites, review the dataset's preferences.xml and other top-level files before you import it.

Set Up a Sandbox

Sandboxes have no replication: import data and set up the storefront directly.

# Create a sandbox (billable) and save a connection for it
b2c sandbox create --realm abcd --ttl 0 --wait
b2c setup instance create my-sandbox --hostname abcd-001.dx.commercecloud.salesforce.com --active

# Import a dataset and rebuild search indexes
b2c job import ./storefront-datasets/marketstreet --show-log
b2c job run Reindex --wait
b2c sites list

# Create a Storefront Next storefront for the site
b2c mrt project create "Market Street" --site MarketStreet --mrt-backend scapi

The Foundations, Market Street, and Beauty Next datasets include a Reindex job. For other sites, run the system search index jobs; see system jobs with custom request bodies.

Storefront creation runs asynchronously. Check progress with b2c mrt project get -p <project-id> --mrt-backend scapi, then get the project configuration from the storefront in Business Manager. You can also use storefront setup in Business Manager instead of mrt project create; see Storefront Next.

Example prompt

Set up my sandbox my-sandbox with the Market Street dataset for Storefront Next 1.4.0: import it, rebuild the search indexes, and create a Storefront Next storefront for the site.

Set Up a Realm

Set up staging completely, then replicate to production and development, then connect the storefront on each target.

1. Prepare Staging

Import your site data, or a dataset for a demo site, rebuild the search indexes, and create the storefront:

b2c job import ./storefront-datasets/marketstreet -i staging --show-log
b2c job run Reindex -i staging --wait
b2c mrt project create "Market Street" --site MarketStreet -i staging --mrt-backend scapi

For cartridge storefronts, deploy and activate a code version; see code commands. Then set the site cartridge path, and add cartridges with custom job steps or Business Manager extensions to the Business Manager path; both replicate with the site:

b2c sites cartridges set "app_custom:app_storefront_base" --site-id MarketStreet -i staging
b2c sites cartridges add my_jobs --bm -i staging

Staging instances normally require two-factor (mTLS) code upload, so cartridge uploads without a client certificate fail, usually with 403 Forbidden. On legacy realms, the client certificate is signed by a CA bundle from Salesforce Support and uploads go to the cert.staging hostname. On Hyperforce realms, you register your own CA through eCDN; see Set Up Two-Factor Code Upload. To configure the certificate, see Two-Factor Authentication.

If your cartridges register hooks for the Commerce API, also turn on hook execution in Administration > Global Preferences > Feature Switches. Otherwise the hooks don't run.

2. Replicate to Production

Replicate from staging with replication jobs in three steps: code, global data, then site data. Global data creates the site on the target, so on the first replication, run it before site data. The b2c-replication skill has the job definitions.

b2c job run Replicate-Code -i staging --wait --show-log
b2c job run Replicate-Global -i staging --wait --show-log
b2c job run Replicate-MarketStreet -i staging --wait --show-log

Replication changes production. Review what each job replicates before you run it.

Data replication doesn't carry job definitions, inventory lists, or SLAS clients. Import job definitions and inventory on production (for example with a production-only import set), and create SLAS clients there. A newly replicated site can stay in maintenance on production until you bring it online. Code deployed to staging reaches production only by code replication, so replicate again after each fix.

3. Connect the Storefront

Storefronts do not replicate. Creating a storefront on production makes a second Managed Runtime project. To keep staging and production in one project, export the storefront from staging and import it on production:

b2c job export --storefront market-street -i staging --output ./storefront-export
b2c job import ./storefront-export/<archive-name> -i production --wait-for-storefront --show-log

The storefront import requires the user-id in the export to be an Account Manager user who is authorized for the target. An export made with client credentials records the API client's service user; edit user-id before importing. Verify with b2c mrt env list -p <project-id> -i production --mrt-backend scapi. For all import requirements, see Add Another Instance.

Example prompt

Our new realm has staging and production configured. Set up the Market Street dataset on staging with a Storefront Next storefront, then replicate it to production and connect the same Managed Runtime project there. Ask me before each change.

Troubleshooting

Problem	What to check
Import fails with a generic error	Rerun with --show-log; the cause is in the [DATAERROR] lines.
There must be a root directory with the same name as the archive	Rename the ZIP or its root folder to match.
Search returns no products	Rebuild the search indexes on that instance.
First site replication fails with Optimistic locking failure or a generic error	Replicate global data first, then site data, as separate jobs.
Storefront import reports a user that is not authorized	Set user-id in the exported storefront XML to an authorized user.

When something fails after launch, see Operations.

Related

• Storefront Next — environment variables, logs, and deployments after setup
• Operations — job health and incident investigation
• Safety Mode — policies and confirmation for shared instances
• Sandbox commands, Job commands, MRT commands