Clone On-Demand Sandboxes

Use on-demand sandbox cloning to create exact replicas of existing sandboxes in minutes, not hours. It helps teams move faster while reducing risk by providing fully isolated environments for development, testing, and operational workflows.

With a single API call, provision a fully isolated replica of your sandbox that includes your database, application code, platform configurations, and all configured feature toggles.

To maintain a consistent and reliable clone, the source sandbox is automatically placed in a protected Stopped state during the initial backup phase of the cloning process. This safeguard guarantees data integrity and configuration consistency. After the backup completes, the source sandbox becomes available again, while the remaining clone phases continue in the background.

Each cloned sandbox is fully isolated, with dedicated compute, storage, and database resources.

Typical use cases include:

• Reproducing production bugs safely without impacting live systems
• Validating disaster recovery plans in isolated replicas
• Spinning up development or test environments for teams quickly
• Validating upgrades and configuration changes before deployment
• Testing feature or performance changes before deployment
• Supporting CI/CD pipelines with on-demand test environments
• Providing realistic training or experimentation environments
• Optimizing costs by cloning sandboxes only when needed

A sandbox clone includes:

• Database schema and data
• Custom code and cartridges
• Storefront, site data, and configurations
• Catalogs and pricebooks
• Orders and content data
• Feature toggles
• Maintenance pages
• Standard platform configuration files

The following data is excluded to protect security, privacy, and tenant integrity:

• Logs and jobs history
• Customer PII and GDPR-related data
• Analytics data
• Geolocation data
• Order activity
• Exchange rate data
• Change logs
• Tenant-specific configurations

Sensitive data is either omitted or transformed to ensure compliance with platform security and privacy requirements.

The cloning process includes six detailed steps grouped into four main progress stages:

1. Prep Instance
   • Validation: Checks the source sandbox status, permissions, and resource availability.
2. Data Backup
   • Backup Creation: Creates a consistent snapshot of the source database, sharedata and configurations.
3. Data Restore
   • Target Provisioning: Allocates compute, storage, and network resources for the new sandbox.
   • Data Restoration: Copies database tables, indexes, and files to the cloned environment.
   • Configuration Transformation: Updates system files and credentials to ensure independence.
4. Post Validation
   • Activation: Validates sandbox health, tests connectivity, and makes the clone available.

Total duration is typically 10–30 minutes, depending on sandbox size and data volume.

The source sandbox is unavailable only during the initial backup phase of the clone operation. Once the backup is complete, the source sandbox becomes available again. If the source sandbox was running when the clone operation was initiated, it’s automatically restarted after the backup completes. If it was already stopped, it remains in the stopped state.

The remaining phases of the clone operation continue in the background and don’t require the source sandbox to be stopped.

Although the source sandbox becomes available before the clone operation finishes, you can’t start another clone from the same source until the current clone completes. See the Sandbox Cloning FAQ for more details.

A clone request can target either a single sandbox (one-to-one cloning) or multiple sandboxes (one-to-many cloning), with up to five target sandboxes per request. With one-to-many cloning, the source sandbox is backed up once, and that backup is used to restore all target sandboxes in parallel. The source availability behavior remains the same regardless of the number of targets.

Each target sandbox progresses through cloning independently. If one target encounters an error, the remaining targets continue processing and can complete successfully.

To clone sandboxes, you need:

Account Requirements

• Sandbox API User role assigned in B2C Commerce Account Manager with realm/tenant-level access.

Source Sandbox Requirements

• Source sandbox must be in Running or Stopped state
• Source sandbox should be in Enabled state
• Source sandbox must not have pending operations
• Permissions to access source sandbox data

Sandbox cloning is available through the B2C Commerce On-Demand Sandbox REST API. Use the clone API to programmatically create and manage sandbox clones, giving developers and admins full control over provisioning and monitoring of the clones.

Access documentation for the Clone APIs and issue API calls from the Sandbox API user interface at https://admin.dx.commercecloud.salesforce.com/. Click Authorize to log in with the API Client ID you configured using Account Manager.

Initiate a clone operation using the POST endpoint.

Request

1POST /sandboxes/{sandboxId}/clones HTTP/1.1
2Host: admin.dx.commercecloud.salesforce.com
3Authorization: Bearer {access_token}
4Content-Type: application/json
5{
6  "targetProfile": "xlarge",
7  "emails": ["email1@example.com"],
8  "ttl": 24
9}

cURL

1curl -X 'POST' \
2  'https://<host>/api/v1/sandboxes/{sandboxId}/clones' \
3  -H 'accept: application/json' \
4  -H 'authorization: Bearer <token>' \
5  -H 'Content-Type: application/json' \
6  -d '{
7  "targetProfile": "medium",
8  "emails": [
9    "email1@example.com"
10  ],
11  "ttl": 24
12}'

Parameters

Success Response (201 Created)

1{
2  "cloneId": "abcd-001-180620251331"
3}

The cloneId can be used to track the clone operation status.

Error Responses

400 Bad Request - Illegal Argument

1{
2  "kind": "Status",
3  "code": 400,
4  "status": "Failure",
5  "error": {
6    "status": "Failure",
7    "message": "Profile downgrade not allowed. Current profile: large, Requested profile: medium. Only same profile or upgrades are permitted.",
8    "reason": "IllegalArgument"
9  }
10}

403 Forbidden - AccessDenied

1{
2  "kind": "Status",
3  "code": 403,
4  "status": "Failure",
5  "error": {
6    "status": "Failure",
7    "message": "User doesn't have access to this realm",
8    "reason": "AccessDenied"
9  }
10}

404 Not Found - Sandbox not found

1{
2  "kind": "Status",
3  "code": 404,
4  "status": "Failure",
5  "error": {
6    "status": "Failure",
7    "message": "Sandbox '34801747-1011-43d0-a3b5-5d46f1b49dfb' doesn't exist.",
8    "reason": "SandboxNotFound"
9  }
10}

Set targetCount to a value from 2–5 to create multiple sandbox clones from the same source in a single request. The source sandbox is backed up once, and the backup is used to create each target sandbox in parallel. This approach reduces source downtime compared to submitting separate one-to-one clone requests.

To create multiple clones, add targetCount to the request body.

Request

1POST /sandboxes/{sandboxId}/clones HTTP/1.1
2Host: admin.dx.commercecloud.salesforce.com
3Authorization: Bearer {access_token}
4Content-Type: application/json
5{
6  "targetProfile": "xlarge",
7  "targetCount": 3,
8  "emails": ["email1@example.com"],
9  "ttl": 24
10}

cURL

1curl -X 'POST' \
2  'https://<host>/api/v1/sandboxes/{sandboxId}/clones' \
3  -H 'accept: application/json' \
4  -H 'authorization: Bearer <token>' \
5  -H 'Content-Type: application/json' \
6  -d '{
7  "targetProfile": "medium",
8  "targetCount": 3,
9  "emails": [
10    "email1@example.com"
11  ],
12  "ttl": 24
13}'

Success Response (201 Created)

1{
2  "cloneId": "abcd-001-1784379488544",
3  "batchId": "batch-abcd-001-1784379488543-dfa36a1d",
4  "siblingCloneIds": [
5    "abcd-001-1784379488544",
6    "abcd-001-1784379488545",
7    "abcd-001-1784379488546"
8  ]
9}

Use the individual clone IDs in siblingCloneIds to monitor each target clone. See Monitor Sandbox Clone Operations.

Error Responses

400 Bad Request - Illegal Argument

1{
2  "kind": "Status",
3  "code": 400,
4  "status": "Failure",
5  "error": {
6    "status": "Failure",
7    "message": "targetCount must be between 1 and 5. Requested: {n}",
8    "reason": "IllegalArgument"
9  }
10}

Monitor the progress of a clone operation using the clone ID and source sandbox ID. This can also be used to retrieve details for a specific cloned sandbox.

Request

1GET /sandboxes/{sandboxId}/clones/{cloneId}
2Host: admin.dx.commercecloud.salesforce.com
3Authorization: Bearer {access_token}
4Content-Type: application/json

cURL

1curl -X 'GET' \
2  'https://<host>/api/v1/sandboxes/<sandboxId>/clones/<cloneId>' \
3  -H 'accept: application/json' \
4  -H 'authorization: Bearer <token>' \
5  -H 'Content-Type: application/json'

Parameters

Success Response (200 OK)

1{
2  "cloneId": "abcd-001-1771055271197",
3  "realm": "abcd",
4  "sourceInstance": "001",
5  "targetInstance": "002",
6  "sourceInstanceId": "0c7bd46d-3300-4880-984f-cf8df01685e6",
7  "targetInstanceId": "2b2d1805-a66f-4b07-943f-9ef6808f5efa",
8  "targetProfile": "medium",
9  "createdAt": "2026-02-14T07:45:07.742Z",
10  "createdBy": "test@example.com",
11  "lastUpdated": "2026-02-14T07:45:07.742Z",
12  "status": "IN_PROGRESS",
13  "elapsedTimeInSec": 240,
14  "progressPercentage": 23,
15  "lastKnownState": "Data Backup In Progress",
16  "customCodeVersion": "SFRA_01_01_2026",
17  "storefrontCount": 1,
18  "filesystemUsageSize": 1024,
19  "databaseTransferSize": 2048
20}

For a target that’s part of a one-to-many batch, the response also includes batchId and siblingCloneIds. Each target has its own cloneId and its own independent status, so poll each cloneId from siblingCloneIds separately. One target completing, failing, or still running has no effect on the reported status of the others.

Response Fields

Clone Status Values

Error Responses

403 Forbidden - AccessDenied

1{
2  "kind": "Status",
3  "code": 403,
4  "status": "Failure",
5  "error": {
6    "status": "Failure",
7    "message": "User doesn't have access to this realm",
8    "reason": "AccessDenied"
9  }
10}

404 Not Found - Invalid Sandbox Id

1{
2  "kind": "Status",
3  "code": 404,
4  "status": "Failure",
5  "error": {
6    "status": "Failure",
7    "message": "DB entry for id '0c7bd46d-3300-4880-984f-cf8df01685e6' doesn't exist",
8    "reason": "NotFound"
9  }
10}

404 Not Found - No Clone Found

1{
2  "kind": "Status",
3  "code": 404,
4  "status": "Failure",
5  "error": {
6    "status": "Failure",
7    "message": "No clone found with id 'zyom-002-017-180620251331'",
8    "reason": "NotFound"
9  }
10}

Fetch details of all clone operations associated with a specific sandbox.

Request

1GET /sandboxes/{sandboxId}/clones
2Host: admin.dx.commercecloud.salesforce.com
3Authorization: Bearer {access_token}
4Content-Type: application/json

cURL

1curl -X 'GET' \
2  'https://<host>/api/v1/sandboxes/<sandboxId>/clones' \
3  -H 'accept: application/json' \
4  -H 'authorization: Bearer <token>' \
5  -H 'Content-Type: application/json'

Parameters

Success Response (200 OK)

1{
2  "clones": [
3    {
4      "cloneId": "abcd-001-1771055271197",
5      "realm": "abcd",
6      "sourceInstance": "001",
7      "targetInstance": "002",
8      "sourceInstanceId": "0c7bd46d-3300-4880-984f-cf8df01685e6",
9      "targetInstanceId": "2b2d1805-a66f-4b07-943f-9ef6808f5efa",
10      "targetProfile": "medium",
11      "createdAt": "2026-02-14T07:45:07.742Z",
12      "createdBy": "test@example.com",
13      "lastUpdated": "2026-02-14T07:45:07.742Z",
14      "status": "IN_PROGRESS",
15      "elapsedTimeInSec": 240,
16      "progressPercentage": 23,
17      "lastKnownState": "Data Backup In Progress",
18      "customCodeVersion": "SFRA_01_01_2026",
19      "storefrontCount": 1,
20      "filesystemUsageSize": 1024,
21      "databaseTransferSize": 2048
22    }
23  ]
24}

Response Fields

Clone Status Values

Error Responses

403 Forbidden - AccessDenied

1{
2  "kind": "Status",
3  "code": 403,
4  "status": "Failure",
5  "error": {
6    "status": "Failure",
7    "message": "User doesn't have access to this realm",
8    "reason": "AccessDenied"
9  }
10}

404 Not Found - Invalid Sandbox Id

1{
2  "kind": "Status",
3  "code": 404,
4  "status": "Failure",
5  "error": {
6    "status": "Failure",
7    "message": "DB entry for id '0c7bd46d-3300-4880-984f-cf8df01685e6' doesn't exist",
8    "reason": "NotFound"
9  }
10}

After cloning completes, you must manually update (if any):

• Custom tenant-specific configurations
• Hard-coded URLs in custom cartridges or scripts
• Third-party service URLs and API endpoints
• Keystore references and certificates tied to the source sandbox
• Custom jobs or schedules that reference the source instance

Choose Appropriate Resource Profiles

Select the profile that meets your requirements. For cloning, the target profile should be the same size or larger than the source sandbox profile.

Review Custom Configurations

After cloning completes, test all integrations and custom configurations. Update third-party endpoints, keystores, and Business Manager customizations that reference the source sandbox.

Manage Cloned Sandboxes

Delete cloned sandboxes when no longer needed to reduce credit consumption.

Plan Clone Operations

Where feasible, execute large clone operations during times when sandbox usage is low.

Save Your Work

During the initial backup phase of the clone process, the source sandbox is stopped. Make sure to save any open work before triggering the clone operation.

Monitor Clone Progress

Monitor the progress of a clone using the Monitor Clone Progress API. Poll the API every 30–60 seconds to check status, but avoid excessive polling, which may trigger rate limits. For a one-to-many clone, poll each target’s cloneId independently. Don’t assume all targets finish at the same time or that one target’s failure affects the others.

Set Time-to-Live Values

Configure the ttl parameter to automatically clean up temporary clones and avoid consuming unnecessary credits.

Resume Work on the Source Early

The source sandbox becomes available again shortly after the clone starts, once the backup stage completes. You don’t need to wait for the full clone to finish before resuming work on the source. You still can’t trigger a new clone on that same source until the current one completes, even though the source itself is available again.

Plan Multi-Target Requests

When cloning to multiple targets, the source is stopped once, for the duration of the single shared backup step, not once per target. The targetProfile, emails, and ttl values apply to the entire batch. If different targets need different settings, submit separate clone requests, or clone with shared settings and adjust individual targets afterward using the Sandbox Update API (PATCH /sandboxes/{sandboxId}).

Q. What state must the source sandbox be in to perform a clone?
A. The source sandbox must be in an Enabled state, either Running or Stopped, to be successfully cloned.

Q. What happens to the source sandbox during cloning?
A. It’s placed in a Stopped state during the initial backup phase to protect data integrity. After the backup completes, the source becomes available again, although you can’t start another clone from it until the current clone finishes.

Q. Can multiple clone operations run from the same source sandbox at the same time?
A. No. Only one clone can run per source sandbox at a time, however different source sandboxes can be cloned simultaneously.

Q. Where is the cloned sandbox created?
A. It’s created in the same realm as the source sandbox.

Q. Are platform configuration files updated automatically during cloning?
A. Standard platform configurations are updated automatically. Custom configurations must be reviewed manually.

Q. Are tenant-specific configurations and customizations updated automatically?
A. No. Tenant-specific configurations, custom keystores, certificates, and Business Manager customizations aren’t updated automatically.

Q. Can a clone operation be paused or resumed?
A. No. Once started, a clone operation can’t be paused or resumed.

Q. How long does cloning usually take?
A. It typically takes 10–30 minutes. In rare cases, it may take up to 60 minutes. If it exceeds 60 minutes, the process fails and the source sandbox is restored.

Q. Are there any credit requirements for cloning?
A. Yes. A sufficient credit balance is required for both the clone operation and the target sandbox uptime.

Q. What happens to feature toggles during cloning?
A. Any manually set or customized feature toggles are copied to the cloned sandbox.

Q. What is the default minimum TTL (Time To Live) for a cloned sandbox?
A. The minimum TTL is 24 hours to avoid accidental deletion during setup.

Q. Can I clone a sandbox to a profile lower than the current profile of the source sandbox?
A. No. The cloned sandbox can have a profile that is the same as or higher than the source sandbox’s profile, but not lower.

Q. What happens if I accidentally delete the source sandbox after successfully creating the clone?
A. Once the clone sandbox is successfully created, it operates as an independent sandbox. Deleting the source sandbox will have no impact on the cloned sandbox.

Q. What happens if I don’t include the emails attribute when calling the Create Clone API?
A. If you don’t explicitly provide the emails attribute, the cloned sandbox won’t inherit or copy the email settings from the source sandbox by default.

Q. Can I clone a sandbox to more than one target at once?
A. Yes. Set targetCount to a value from 1–5 in your clone request. The source is backed up once and restored to all targets concurrently.

Q. Is there a limit on how many targets I can clone to at once?
A. Yes. targetCount accepts values from 1–5.

Q. If one target fails in a one-to-many clone, do the others fail too?
A. No. Each target is tracked and processed independently. A failure on one target has no effect on the others. Check each target’s cloneId status individually.

Q. Can I set a different profile, TTL, or notification email list for each target in a one-to-many clone?
A. No. targetProfile, ttl, and emails apply to the whole request, not per target. Submit separate clone requests if targets need different settings, or use the Sandbox Update API to adjust individual targets afterward.

Q. If my source sandbox becomes available again early, can I start another clone on it right away?
A. No. Although the source sandbox becomes available shortly after the backup stage completes, you can’t trigger a new clone on that same source until the current clone operation finishes (Completed or Failed). The early availability lets you resume other work on the source sooner. It doesn’t open a new clone slot.

j

Announcements

Choose Your B2C Commerce Storefront Type

Universal Commerce Protocol (UCP) Integration

B2C Commerce

Quick Start

Overview of B2C Commerce

Get Set Up

Get B2C Commerce User Access

On-Demand Sandboxes

Get Started with On-Demand Sandboxes

Use the Sandbox API to Manage On-Demand Sandboxes

Manage Sandboxes from Control Center

Clone On-Demand Sandboxes

Develop With Your On-Demand Sandbox

Enable Einstein Activities

Build Your Site

Customize and Extend

Follow Best Practices

Test and Launch

Monitor and Maintain

Track Analytics

B2C Commerce Intelligence JDBC Driver

SCAPI

Storefront Next

Composable Storefront

Storefront Reference Architecture (SFRA)

Commerce Apps ISV Developer Guide

B2C Commerce Solutions

B2C Commerce Release Notes

B2C Commerce Reference Information

Ask the Community