Use the Sandbox API to Manage On-Demand Sandboxes

Use the Sandbox API to create and manage on-demand sandboxes.

The B2C Commerce CLI wraps the Sandbox API with an easy-to-use workflow, so you can manage sandbox lifecycle from your terminal without writing raw API calls. To install the tool and authenticate, see B2C CLI, MCP and Tooling SDK.

1# Create a new on-demand sandbox in a realm and wait for it to be ready
2b2c sandbox create --realm abcd --wait
3
4# Create a larger sandbox with a 48-hour TTL and auto-scheduled start/stop
5b2c sandbox create --realm abcd --profile large --ttl 48 --auto-scheduled
6
7# List your sandboxes
8b2c sandbox list
9
10# Get sandbox details (including hostname and state)
11b2c sandbox get <sandbox-id>
12
13# Start, stop, or restart a sandbox
14b2c sandbox start <sandbox-id>
15b2c sandbox stop <sandbox-id>
16b2c sandbox restart <sandbox-id>
17
18# Reset a sandbox to a clean state
19b2c sandbox reset <sandbox-id>
20
21# Delete a sandbox when you're done
22b2c sandbox delete <sandbox-id>

For the full command reference, see Sandbox Commands in the B2C DX documentation.

Access documentation for the Sandbox API and issue API calls from the Sandbox API user interface.

The Sandbox API user interface is available here:

https://admin.dx.commercecloud.salesforce.com/

Click Authorize to log in with the API Client ID you configured using Account Manager.

For details about the API call, expand the API method and click the Model for each call. To issue an API call from the Sandbox API user interface, click Try it out for any method. Edit the Example Values in the request body and click Execute.

Many of the Sandbox API calls require you to provide a sandbox’s ID. Get the ID using the GET/sandboxes method.

1. To open the Sandbox API user interface, go to B2C Commerce Sandbox API.

2. Click Authorize.

3. Enter the API client ID for the Sandbox API.

4. To dismiss the authorization window and return to the Sandbox API user interface, click Close.

5. In the Sandboxes section of the Sandbox API user interface, click to expand the GET/sandboxes method.

6. From the include_deleted dropdown menu, select true to include deleted sandboxes in the list of sandboxes returned.

7. In the filter_params field, specify criteria to narrow the sandbox results. This table lists the supported filter values:

   If no filter parameters are provided, the API returns all matching sandboxes. The realm filter only shows sandboxes from realms you can access.

   Note

   Filter Name	Description	Example
   realm	Filter sandboxes by realm name (case-insensitive).	realm=zzzt
   state	Filter sandboxes by their current state. Possible values are: deleted, failed, new, started, stopped, unknown, and upgrading.	state=started
   resourceProfile	Filter sandboxes by resource profile.	resourceProfile=medium
   createdBy	Filter sandboxes by the user who created them.	createdBy=user1
   tags	Filter sandboxes by tags (comma-separated within square brackets).	tags=[tag1,tag2]

   Examples:

   • Filter by realm and state: realm=testrealm&state=active
   • Filter by realm and resource profile: realm=production&resourceProfile=large
   • Filter by realm, state, resource profile, created by, and tags: realm=testrealm&state=active&resourceProfile=medium&createdBy=admin&tags=[tag1,tag2]

8. Click Try it out.

9. Click Execute.

   

Manage your sandboxes more efficiently by assigning resource profiles to them based on your needs. Resource profiles define the disk, CPU, and memory allocation for their assigned sandboxes.

Assigning resource profiles to sandboxes provides several benefits:

• Assign different size resource profiles to sandboxes according to your performance needs.
• Developers can more easily maintain sandbox content, ensuring that configuration is aligned with the production environment.
• When running automated tests, use the full data set.
• View sandbox usage information by profile using the GET/realm/{realm}/usage method.

Assign one of three discrete profiles to each on-demand sandbox. This table describes the settings for each resource profile:

Define an on-demand sandbox with a resource profile using the POST/sandboxes method.

1. To open the Sandbox API user interface, go to B2C Commerce Sandbox API.

2. Click Authorize.

3. Enter the API client ID for the Sandbox API.

4. To dismiss the authorization window and return to the Sandbox API user interface, click Close.

5. In the Sandboxes section of the Sandbox API user interface, click to expand the POST/sandboxes method.

6. Click Try it out.

7. In the request body, specify the desired resource profile.

8. If you’re using an Operation Scheduler to manage this sandbox, change the autoScheduled parameter to true.

9. If applicable, enter values for OCAPI or WebDAV settings, or delete those sections of the request body.

10. Click Execute.

    

To check a sandbox’s status use the GET/sandboxes/{sandboxId} method.

1. To open the Sandbox API user interface, go to B2C Commerce Sandbox API.

2. Click Authorize.

3. Enter the API client ID for the Sandbox API.

4. To dismiss the authorization window and return to the Sandbox API user interface, click Close.

5. In the Sandboxes section of the Sandbox API user interface, click to expand the GET/sandboxes/{sandboxId} method.

6. Click Try it out.

7. Enter the sandbox ID.

8. Click Execute.

   

Realm administrators can configure when to start and stop sandboxes to better manage on-demand sandbox usage. For example, with an Operation Scheduler, turn sandboxes on or off at specific times on specified weekdays.

When creating an Operation Scheduler, keep these considerations in mind:

• For the scheduler to manage an on-demand sandbox, you must set the sandbox autoScheduled parameter to true.

• Scheduler times use Zulu (Coordinated Universal Time) or Greenwich Mean Time (+offset) format.

• Default Operation Scheduler settings turn all auto-scheduled sandboxes on Monday through Friday at 08:00:00+03:00 and off on the same weekdays at 19:00:00Z.

• To turn off the scheduler, set the startScheduler and stopScheduler parameters to null. For example:

  

Create an Operation Scheduler using the PATCH/realms/{realm}/configuration method.

1. To open the Sandbox API user interface, go to B2C Commerce Sandbox API.

2. Click Authorize.

3. Enter the API client ID for the Sandbox API.

4. To dismiss the authorization window and return to the Sandbox API user interface, click Close.

5. (Optional) In the Realms section of the Sandbox API user interface, click to expand the PATCH/realms/{realm}/configuration method.

6. (Optional) In the Sandbox section of the Sandbox API user interface, click to expand the POST/sandboxes method.

7. (Optional) To update an operation scheduled, In the Sandbox section of the Sandbox API user interface, click to expand the PATCH /sandboxes/{sandboxId} method.

8. Click Try it out.

9. In the request body, modify the startScheduler and stopScheduler weekdays and times to when you want to start and stop auto-scheduled sandboxes.

10. Specify the four-letter ID for the realm.

11. Click Execute.

    The API creates an Operation Scheduler that manages all sandboxes in the realm with their autoScheduled parameter set to true.

    

    

To stop, start, or reset (DBINIT) a sandbox, use the POST/sandboxes/{sandboxId}/operations method. Stopped sandboxes consume fewer credits than running sandboxes.

1. To open the Sandbox API user interface, go to B2C Commerce Sandbox API.

2. Click Authorize.

3. Enter the API client ID for the Sandbox API.

4. To dismiss the authorization window and return to the Sandbox API user interface, click Close.

5. In the Sandboxes section of the Sandbox API user interface, click to expand the POST/sandboxes/{sandboxId}/operations method.

6. Click Try it out.

7. Edit the operation in the request body to specify what you want to do.

   • start: Makes a sandbox in a stopped state accessible again.
   • stop: Stops a sandbox.
   • reset: Refreshes a sandbox instance with a new database using the DBINIT process.
   • restart: Makes a sandbox that is in a stopped state accessible again. Stops an active sandbox and starts it again.

8. Enter the sandbox ID.

9. Click Execute.

   

10. Check the status of the sandbox to make sure it has changed accordingly. See Check the Status of a Sandbox.

You currently don’t have to allowlist On-Demand Sandbox IP addresses to gain access to them. However, you might need to allowlist On-Demand Sandbox IP addresses on other systems or firewalls to communicate with On-Demand Sandboxes.

When allowlisting sandbox IP addresses, keep the following in mind:

• We don’t restrict sandbox outbound data. If your receiving systems reside within the same VPN or an unrestricted network,allowlisting the On-Demand Sandbox IP addresses is unnecessary.
• When allowlisting IP addresses for On-Demand Sandbox access, include all outboundIps and systemIps addresses to make sure the system can access them.

If you want to allowlist sandbox IP addresses on another system, get the IP addresses using the GET/system method.

1. To open the Sandbox API user interface, go to B2C Commerce Sandbox API.

2. Click Authorize.

3. Enter the API client ID for the Sandbox API.

4. To dismiss the authorization window and return to the Sandbox API user interface, click Close.

5. In the Common section of the Sandbox API user interface, click to expand the GET/system method.

6. Click Try it out.

7. Click Execute.

   

8. Use the retrieved outbound IP addresses when allowlisting addresses on an external system.

Test storefronts by reusing a hostname alias for multiple sandboxes, or create a hostname alias that is unique to one sandbox.

Reuse a hostname over multiple sandboxes by creating a non-unique alias and generating a registration link to access the sandbox.

Reuse a hostname alias to do local testing by accessing the sandbox without a proxy or CDN between the node and the sandbox. This option requires sending a cookie manually with every request or by using a registration link.

Define a reusable on-demand sandbox alias using the POST /sandboxes/{sandboxId}/aliases method.

1. To open the Sandbox API user interface, go to B2C Commerce Sandbox API.

2. Click Authorize.

3. Enter the API client ID for the Sandbox API.

4. To dismiss the authorization window and return to the Sandbox API user interface, click Close.

5. In the Common section, click to expand the GET/realms/{realm}/system method.

6. Click Try it out.

7. Click Execute.

   

   The results contain one or more string values. These values appear as IP addresses surrounded by quotation marks, for example, “3.210.241.243”.

8. Copy a string value under systemIps and add it, along with the custom hostname, to your local hosts file, for example, 3.210.241.243 www.merchant.com. You need admin rights to edit this file.

9. In the Sandboxes section of the Sandbox API user interface, click to expand the GET /sandboxes method

10. Click Try it out.

11. Click Execute.

    

12. From the results, copy the desired Sandbox ID.

13. In the Sandboxes section, click to expand the POST /sandboxes/{sandboxId}/aliases method

14. Click Try it out.

15. Register the hostname by editing the alias value (1), adding the hostname (2), and specifying the Sandbox ID copied (3).

    

    The API payload supports a unique hostname parameter. Unless you explicitly set it, the unique parameter is assumed to be false. If you’re using one hostname for multiple sandboxes, either omit the unique setting from the payload or specify a value of false.

    Note

    1{
    2"name": "www.merchant.com",
    3"unique": false
    4}

16. Click Execute.

    The call response generates a cookie and provides a registration URL.

17. Copy the registration URL from the call response, and paste the link into a browser.

    After a short time, the browser redirects to the sandbox alias where you can perform SEO testing.

When testing REST APIs, you typically don’t use default browser access to a site. When using tools like Curl or Postman, you define a cookie header manually using the hostname and information that you obtain from the GET /system API response.

For example,

1curl -X GET -k -H 'Cookies:
2b2codds_df69b6df-a4fb-3e8b-ada3-d0ded26e9fe0=83f05593-6272-382f-be1c-bc8e5021a243'
3'https://www.merchant.com/dw/shop/v20_1/products/foo'

To use a unique hostname alias to access a sandbox, create or use an already existing DNS CNAME record that points to the sandbox origin, or create a unique hostname alias using the aliases API.

If you choose to create a unique hostname alias using the aliases API, you must add a text record containing a unique domainVerificationRecord value to either the DNS sub- or root-domain. Unlike reusing a hostname alias, this option doesn’t require using a registration link or any cookies.

Define a unique on-demand sandbox alias using the POST /sandboxes/{sandboxId}/aliases method.

1. To open the Sandbox API user interface, go to B2C Commerce Sandbox API.

2. Click Authorize.

3. Enter the API client ID for the Sandbox API.

4. To dismiss the authorization window and return to the Sandbox API user interface, click Close.

5. To test directly from any local system, add the string value, along with the custom hostname, as an address record, to your DNS subdomain or root domain. For example if your realm id is “abcd”, your DNS Record will be:

   1www.merchant.com CNAME abcd.dx.commercecloud.salesforce.com

6. Click Try it out.

7. Click Execute.

   

8. From the results, copy the desired Sandbox ID.

9. In the Sandboxes section of the Sandbox API user interface, click to expand the POST /sandboxes/{sandboxId}/aliases method

10. Click Try it out.

11. Register the hostname by editing the alias value (1), adding the hostname (2), and specifying the copied Sandbox ID (3), along with a uniqueness value of true.

    1{
    2"name": "www.merchant.com",
    3"unique": true
    4}

    

12. Click Execute.

13. Using the domainVerificationRecord value from the response body, add a verification text record to either the DNS subdomain or root domain.

    1www.merchant.com  TXT  "sfcc_verification_abcd=8ee12469a9f6cf17af34eea237595d53608475f8a04840f03c2434bbbd51288d"

    If your domain registrar doesn’t allow a TXT entry and a CNAME entry for the same subdomain, add the same text record entry to the root domain and subdomain. See, RFC 1912–Common DNS Operational and Configuration Errors

    Note

    1dev.merchant.com 3600 IN CNAME abcd.dx.commercecloud.salesforce.com.@ 3600 IN TXT "sfcc_verification_abcd=8ee12469a9f6cf17af34eea237595d53608475f8a04840f03c2434bbbd51288d"

14. Use the hostname to access the sandbox alias directly and perform SEO testing.

To automatically generate a certificate for your alias, set requestLetsEncryptCertificate to true . The generated certificate certifies the specific host used during alias creation. The certificate is required to show the storefront as secure. If you don’t generate a certificate, your storefront shows as insecure.

1{
2"name": "www.example.com",
3"unique": true,
4"requestLetsEncryptCertificate": true
5}

Salesforce recommends that you familiarize yourself with the Let’s Encrypt policy.

To delete a sandbox, use the DELETE/sandboxes/{sandboxId} method. Save credits by deleting a sandbox when you don’t need it anymore.

1. To open the Sandbox API user interface, go to B2C Commerce Sandbox API.

2. Click Authorize.

3. Enter the API client ID for the Sandbox API.

4. To dismiss the authorization window and return to the Sandbox API user interface, click Close.

5. In the Sandboxes section of the Sandbox API user interface, click to expand the POST/sandboxes/{sandboxId} method.

6. Click Try it out.

7. Enter the sandbox ID.

8. Click Execute.

   

To check the status of credits on the realm, use the GET/realm/{realm}/usage method. To check the status of credits for a specific sandbox, use the GET/sandboxes/{sandboxId}/usage method.

1. To open the Sandbox API user interface, go to B2C Commerce Sandbox API.

2. Click Authorize.

3. Enter the API client ID for the Sandbox API.

4. To dismiss the authorization window and return to the Sandbox API user interface, click Close.

5. To check the status of credits for the realm, click to expand the GET/realm/{realm}/usage method.

6. Click Try it out.

7. Enter the realm ID.

8. Enter the begin and end date for the usage report.

9. Click Execute.

   

10. To check the status of credits for a sandbox, click to expand the GET/sandboxes/{sandboxId}/usage method.

11. Click Try it out.

12. Enter the realm ID.

13. Enter the begin and end date for the usage report.

14. Click Execute.

    

The on-demand sandbox (ODS) platform sends an email notification when the following events happen.

• The License has expired: The on-demand sandbox platform sends an email notification when the following events happen.

• Sandbox is about to expire (TTL): When a TTL is defined for the sandbox, the ODS sends two notifications to the email addresses associated with the sandbox. The first notification is sent approximately 48 hours before the TTL expires. The second notification is sent approximately 24 hours before the TTL expires. The email addresses that receive the message are the email addresses associated with the Sandbox. If there are no email addresses associated with the Sandbox, the system uses the emails associated with the Realm.

• Sandbox has expired (TTL): When a TTL is defined for the sandbox and the TTL is expired, the on-demand sandbox sends an email notification and the sandbox is deleted.

  The email addresses that receive the message are the email addresses associated with the Sandbox. If there are no email addresses associated with the Sandbox, the system uses the emails associated with the Realm.

To receive email notifications of these events, you associate your email with your realm and sandboxes.

Use the B2C Commerce Developer Sandbox REST API to verify email addresses associated with your realm and ODS.

To check if you have emails associated with your realm, use the getRealmConfiguration GET endpoint. To update the associated email addresses, use the patchRealmConfiguration PATCH endpoint.

To check if you have emails associated with your ODS, use the getSandbox GET endpoint. To update the associated email addresses use the patchSandbox PATCH endpoint. Define the emails during the creation of the sandbox as detailed in the postSandbox POST endpoint.

Salesforce B2C Commerce On-Demand Sandbox (ODS) logs are available in Log Center. This enhancement eliminates the need to use a separate URL to access ODS logs for the first-party instance of Log Center.

1. Start Log Center.

2. Select a region.

3. Select a realm, if you’re unsure of your realm ID, ask your Account Executive (AE) or Customer Service manager (CMS) for assistance.

4. Click Show filtered results.

5. Select Search > Current Search.

6. Under Service Type, select ecom or jwa.

7. To view the ODS logs, from the Host dropdown, select a host.

j

Announcements

Choose Your B2C Commerce Storefront Type

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