Understanding Compatibility Modes

In Salesforce B2C Commerce, compatibility mode refers to a specific B2C Commerce API version where its changes impacted backward compatibility with the previous API version. Not every API version impacts backward compatibility, so only some API versions have a compatibility mode. API versioning enables you to actively select from multiple compatibility modes, with the full knowledge and acceptance of incompatible changes. The ability to select the compatibility mode you want to use enables you to maintain your customizations on a previous compatibility mode, while B2C Commerce introduces new functionality in one or more newer compatibility modes.

Selectable compatibility modes are those that are newer than the active compatibility mode, in addition to the previously active compatibility mode. You can't select a compatibility mode that is older than the previously active one.

Note: Not every release introduces an API version or compatibility mode. We'll try to keep the number of API compatibility modes to a maximum of two per year.

B2C Commerce supports a single active compatibility mode; and maintains a reference to the previously active compatibility mode, to which you can revert, if necessary.

The complete list of compatibility modes available at any time consists of:

When your system was initially provisioned, the active compatibility mode was set to the latest (or most recent) compatibility mode. For example, if you initially provisioned with version 2.10.6, then the active compatibility mode will be 2.10.6 because 2.10.6 introduced a corresponding 2.10.6 API version (compatibility mode).

You can specify how many code version to retain. The oldest, except for the active and previously active code versions, will be automatically removed by B2C Commerce (Sandboxes only).

See Compatibility Mode Considerations for a list of changes included in each compatibility mode. See Managing Code Versions for detailed instructions on configuring and maintaining code versions.

UX Studio

UX Studio automatically knows which compatibility mode is valid, based on communication with the server.

API Documentation

A single API documentation set describes multiple compatibility mode at the class/method level, and potentially multiple compatibility modes for certain methods.

When Do You Need to Change Your Application?

Before activating a new compatibility mode, it's important that you understand the behavioral changes the new mode brings. If the change impacts your application, you might need to modify your application to make it function correctly with the changes and then test. You can only rollback to the previously active compatibility mode if your code is compatible with the old mode (API version). If you write code that takes advantage of the API of a newer version that is incompatible with the old version, you can only rollback if you also revert the respective code.

When using API versioning, you must pay close attention to certain situations: