Reuse a Hostname Alias

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.

Note: 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/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 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).


    Note: 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.
    {
    "name": "www.merchant.com",
    "unique": 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.

What If I Don’t Use a Browser?

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,

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