Use the Sandbox API to Manage On-Demand Sandboxes

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

You can 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. Click Try it out.

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

  8. 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:

  • You can 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, you can use the full data set.
  • You can view sandbox usage information by profile using the GET/realm/{realm}/usage method.

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

Resource ProfileCPU & Memory UnitsStorageRunning Cost (Credits/Minute)Stopped Cost (Credits/Minute)
medium (Default)110 GB10.3
large220 GB20.3
xlarge450 GB40.3

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, you can 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.Realm PATCH method.

    Sandbox POST method.

    Sandbox PATCH method.

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 do not 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 do not 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.
  • The On-Demand sandbox system uses three IP addresses. When allowlisting IP addresses for On-Demand Sandbox access, include all outbound IP addresses to ensure system access.

If you want to allowlist sandbox IP addresses on another system, you can 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.

You can test storefronts by reusing a hostname alias for multiple sandboxes, or you can 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.

Reusing a hostname alias enables you 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.

Before defining a sandbox alias, define a custom host name, such as www.merchant.com, in your site’s alias configuration under Merchant Tools > SEO > Aliases.

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, you can either omit the unique setting from the payload or specify a value of false.

  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,

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

Creating or using an already existing DNS CNAME record provides a global, one-to-one mapping to the sandbox. For this option, you don’t need to use 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 does not require using a registration link or any cookies.

Before defining a sandbox alias, define a custom host name, such as www.merchant.com, in your site’s alias configuration under Merchant Tools > SEO > Aliases.

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:

  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.

  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.

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

  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.

ODS sets the certificate quota at 10 certificates generated per week. When you generate a certificate for my-sbx.production.domain.com you consume Let’s Encrypt quotas from production.domain.com. The quota count applies to any certificate issued, whether through ODS or any other internal tool.

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

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

When you delete a sandbox, it is permanently deleted. The sandbox and its data are no longer available.

  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.