How to change the code Compatibility Mode in Salesforce B2C Commerce Cloud

“How do I update my Compatibility mode to vxx.xx?” This is a question that many have asked over the years, especially with the On-Demand Sandboxes taking the last compatibility mode by default – not providing a way to go back.

So what now? How do you keep your sandboxes all on the same version if some are on an older one?

What is this "Compatibility Mode"?

The easiest way to explain this is by linking the Compatibility Mode to the engine that runs between us (the developers) and the Java engine that runs Salesforce B2C Commerce Cloud.

Commerce Cloud uses an engine based on Apache Rhino, which translates JavaScript to Java. And this engine has versioned releases, each providing new features to keep up with the JavaScript standards (or at least as much as possible).

Forced upgrades are dangerous

Updating the engine can cause some functions that worked in the previous release to break down. The engineering team can only force this new version on us if they give us the time to update the custom code to be compatible with the latest version.

And that is where the choice of “Compatibility Mode” comes in. We can decide for ourselves when to make a move to this new engine (and make use of the new toys that come with it)

The only way is up?

As with all features baked into the Business Manager, Salesforce decides which modes you can use in the interface. And in most cases, the only way is up.

Can we "downgrade"?

If the interface only allows us to upgrade, it is time to find ways to work around that “security”!

hackerman hr

Manipulate the form?

The first weapon we have is our browser console! Can we manipulate the HTML form and add the version we want?

As it turns out… no. There is server-side validation in place. So we need to find another way to hack the system!

To the WebDAV

Let us next see if we can do anything in the WebDAV to manipulate the Compatibility Mode. (Spoiler: We can)

To retrieve the URL for the WebDAV go to:

“Administration > Site Development > Development Setup”

If you open the URL (and have the browser plugin installed), you will get a view such as this:

Click on the active Code Version (this is important)!

Go into the folder, and a file called “.apiversion” will be there.

Inside that file is where the “magic” happens, and it looks something like this:

					#DO NOT EDIT! This is the api version with which *this* code version is compatible. It is managed by the system.
#Tue Aug 01 09:55:45 GMT 2017

This file has an interesting key, specifically “api.version”! You can change that to the version you want to use for your sandbox by downloading it, editing it, and re-uploading it to the same folder.

In this case, we will update it to “18.10”

					#DO NOT EDIT! This is the api version with which *this* code version is compatible. It is managed by the system.
#Tue Aug 01 09:55:45 GMT 2017

Let us head back to the business manager and go to the “Manage Code Versions” screen:

“Administration > Site Development > Code Deployment”

If all has gone well, the code versions have changed to the one in the file!


It depends. Only do this if you have to. In most cases, this is done on older projects already tested on that older Compatibility Mode, and you need to match it.

Please do not go back too far; it is in everyone’s best interest to be on the latest and greatest version of the Rhino Engine!

But developers worldwide have done this many times without any drawbacks! Just make sure you configure a Compatibility Mode that exists!


Table of Contents