Announcement: You can find the guides for Commerce 7.5 and later on the new Elastic Path Documentation site. This Developer Center contains the guides for Commerce 6.13.0 through 7.4.1.Visit new site

This version of Elastic Path Commerce is no longer supported or maintained. To upgrade to the latest version, contact your Elastic Path representative.

What's New for Elastic Path Commerce 6.16.0

What's New for Elastic Path Commerce 6.16.0

Release Highlights

Elastic Path Commerce 6.16.0 offers increased Cortex performance and stability, Cortex localization support, and developer improvements to increase agility and productivity.

A major focus of the release was on Cortex transactional performance. In our standard Cortex benchmark overall transaction throughput increased by a factor of 2.5 and response times were reduced for all transactions. A comprehensive refactoring of the shopping cart was needed to fix stability issues and improve pricing, promotion and tax calculation performance.

Support was added to Cortex for localizing language and currency.

The handling of unavailable cart items was changed to provide greater checkout flexibility.

Developer improvements include an upgrade to Maven 3.3.9, user-defined Quick Links in Cortex Studio, support for customizing Cortex JNDI services, and source code for the Cortex resource layer.

Functional Changes

Core Commerce

Cortex API

  • PB-1444 - Added support for localizing language and currency - see Personalization: Supported Traits.
  • PB-1639 - Added user-defined Quick Links to Cortex Studio.
  • PB-1731 - Carts resource now includes unavailable cart items - see upgrade notes.

Commerce Manager Client

  • PB-1771 - Removed pre-order and back-order limits from product configuration as these are not supported by the journaling inventory strategy - see Announcements and Notices
  • PB-1804 - Disabled "Shop on behalf of" functionality by default - see upgrade notes.

Development Changes

Core Commerce

  • PB-1361 - Moved shared demo data to a separate module in the commerce-data project to reduce duplication of demo data.
  • PB-1442 - Added integration server to extensions smoketests.
  • PB-1551 - Upgraded Maven to 3.3.9 - see upgrade notes.

Cortex API

  • PB-1102 - Removed use of deprecated Representations from the purchases resource.
  • PB-1444 - Updated configuration mechanism to use Declarative Services instead of Blueprint - see upgrade notes.
  • PB-1550 - Released source code for rest-resources modules - see upgrade notes.
  • PB-1717 - Removed Cortex FitNesse tests from the commerce-extensions project - see Announcements and Notices
  • PB-1721 - Simplified encoding of Composite IDs - see upgrade notes.
  • PB-1797 - Changed Maven groupids of rest-resources - see upgrade notes.
  • PB-1807 - Added ability to configure JNDI services in Cortex - see the Configuring JNDI Services section.
  • PB-1895 - Made changes to the Cortex Authentication API - see upgrade notes.

Performance Improvements

Core Commerce

  • PB-687 - Fixed degradation of promotions rules performance caused by inactive promotions.
  • PB-1399 - Refactored shopping cart for performance and stability - see upgrade notes.
  • PB-1462 - Optimized retrieval of rules by promotion code.
  • PB-1560 - Eliminated separate query to determine first-time buyers - see upgrade notes
  • PB-1561 - Optimized retrieval of shipping options.
  • PB-1592 - Eliminated unnecessary read of store on all API requests.
  • PB-1604 - Eliminated excessive tax calculation requests when reading the shopping cart.
  • PB-1671 - Eliminated DB query for pre-order and back-order limits.
  • PB-1679 - Replaced multiple inventory journal rollup queries with a single query for all SKUs in a product.
  • PB-1680 - Eliminated inventory queries for ALWAYS_AVAILABLE items.

Cortex API

  • PB-1589 - Optimized Cortex settings access - see upgrade notes.
  • PB-1591 - Eliminated unnecessary product type query when reading items.
  • PB-1594 - Eliminated repetitive shopping cart and cart order queries when reading the shopping cart.
  • PB-1602 - Fixed request scope cache misses caused by identifier case differences.
  • PB-1603 - Eliminated repetitive shopper and customer queries when reading the shopping cart.
  • PB-1672 - Eliminated duplicate base amount queries when reading items.
  • PB-1682 - Eliminated duplicate customer query on every API request.
  • PB-1686 - Fixed request scope caching not being invoked for internal repository method calls by replacing Spring AOP with AspectJ.

Bug Fixes

Core Commerce

  • PB-194 - Fixed optimistic locking errors when reading the shopping cart memento.
  • PB-1412 - Fixed shopping cart not persisting an item that was added to the cart by a promotion rule.
  • PB-1477 - Fixed build errors caused by invalid Maven build time stamp format.
  • PB-1512 - Fixed NPE when displaying subscription items with a zero purchase price.
  • PB-1700 - Fixed dependency conflicts by replaced activemq-all jar dependency with individual dependencies.
  • PB-1774 - Added missing epdb.validatation.query element for mssql-dev-db profile.
  • PB-1790 - Fixed reading of UTF-8 encoded property files.
  • PB-1791 - Fixed incorrect dates on order notes, shipments, refunds and returns.
  • PB-1792 - Removed the ep-defaults Maven profile as it was not being used.
  • PB-1793 - Fixed inability to connect when SMTP server requires no authentication.
  • PB-1858 - Fixed item availability for disabled products when product is available for pre-order or back-order.

Cortex API

  • PB-439 - Fixed items resource showing item available when out of stock if any item in the product is available.
  • PB-1638 - Fixed Cortex Studio issues when OAuth authentication is disabled.
  • PB-1640 - Fixed zooming into a URI that contains an alias.
  • PB-1827 - Fixed availability resource not included in items that are no longer available.
  • PB-1851 - Fixed inability to return an item that is no longer available.
  • PB-1895 - Fixed problems with processing multiple scopes and roles in Cortex headers
  • PB-1900 - Fixed currency localization for cart line item prices.

3rd Party Library Changes and Upgrades

Library New Version Previous Version
Apache Maven 3.3.9 3.0.5

Upgrade Notes

The Upgrade Guide provides general advice on upgrading Elastic Path projects. Specific upgrade considerations for Core Commerce 6.16.0 and Cortex API 1.16.0 are covered below:

Improved Cortex performance

A major focus of the release was on Cortex transactional performance, with particular attention on browsing and shopping cart performance. Submit order performance was not addressed specifically but benefitted greatly from the general optimizations that were made.

In our standard Cortex benchmark overall transaction throughput increased by a factor of 2.5 and response times were reduced for all transactions.

When upgrading:

  • Be aware that fairly extensive changes to commerce engine and Cortex repository code were required to achieve the performance improvements. This may require refactoring of some of your extension code.

After upgrading you may want to investigate whether there are opportunities to improve the performance of extension functionality.

Upgraded Maven to 3.3.9

You now need to use Maven 3.3.9 to build your project.

When upgrading:

  • Developers should update Maven.
  • Remember to update Maven on your CI servers.

Changed Maven groupids for Cortex resources

In order to optimize Cortex startup behavior it became necessary to distinguish between Cortex resources and RelOS kernel artifacts. To do this, the Maven groupids of all modules in rest-resources were changed from to The groupids of the RelOS kernel artifacts are untouched.

When upgrading:
  • Update dependencies in your extensions project if you have extended Cortex resources.

Released additional Cortex source modules

The source for Cortex rest-resources moduless is now included in the cortex-ep-integration project. The physical layout of the project has been adjusted to accomodate the new modules.

When upgrading:

  • If you have made changes to the cortex-ep-integration project, reorganize the project to the new structure prior to upgrading. This will make it easier to compare changes between release versions.

Simplified encoding of Cortex composite IDs

Cortex Resource implementations that utilized CompositeIdUtils can now skip the Base32 decoding step:

Old Code
String decodedAssetId = Base32Util.decode(encodedAssetId);
Map<String, String> assetFieldValues = CompositeIdUtil.decodeCompositeId(decodedAssetId);
New Code
Map<String, String> assetFieldValues = CompositeIdUtil.decodeCompositeId(encodedAssetId);

Similarly, encoding a composite id has been simplified:

Old Code
String decodedCompositeId = CompositeIdUtil.encodeCompositeId(assetFieldValues);
String encodedCompositeId = Base32Util.encode(decodedCompositeId);
New Code
String encodedCompositeId = CompositeIdUtil.encodeCompositeId(assetFieldValues);

When upgrading:

  • Be aware that composite ID encoding and decoding will fail at runtime if the code is not updated.

Changed Cortex configuration to use Declarative Services

RelOS' configuration mechanism was updated to utilize Declarative Services instead of Blueprint. As a result some changes to the configuration files were made. Each configuration file change is listed below to aid in upgrading your configuration.

Note: If your system does not contain one of these files then your system is using the default configuration settings built into RelOS. You do not need to make any changes or create the configuration file.
  • Renamed file to authClientHost.config to support configuring collections.
  • The new mappings field contains a list of endpoint name to URL mappings.
Old Format
New format


  • Removed configuration file as it was unused.
  • The remote auth client uses the same configuration as the authClientHost.config file. By default RelOS does not use remote auth but instead connects to Commerce Engine directly to authenticate users.
  • Renamed file to oauthTokenExpiry.config to clarify the referred token is an OAuth token.
  • Renamed relos.token.expiry.SECONDS field to seconds.
  • Value must be declared as a long by prefixing the quoted string with 'L'
Old Format
New Format
  • Renamed relos.ROLE_HEIRARCHY field to roles.
  • Changed format of value from comma separated string to a json-like string array.
Old format
New format

Changed Cortex Authentication API

Several changes were made to the Cortex Authentication API:

  • was renamed to
  • was renamed to
  • Authentication methods no longer expect a Set<String> for role or scope parameters, now it’s just a single String.

Optimized Cortex settings access

Several system settings were not being cached for Cortex requests. There was also some confusion regarding the use of refreshStrategyKey in CachedSettingsReader. Currently, the apiRefreshStrategy is the only supported refresh strategy key.

When upgrading:

  • Make sure that setttings accessed during Cortex requests are defined with apiRefreshStrategy.

Refactored shopping cart for performance and stability

A major refactoring of the shopping cart was done to adapt it to a sessionless architecture. The cart was originally designed to work with sticky sessions and exhibited a number of undesirable characteristics when used by Cortex in a sessionless environment. The key issues were:

  • The cart was persisted every time it was read, which degraded performance and caused intermittent optimistic lock exceptions.
  • Promotion rules were executed multiple times while reading the cart, which degraded performance.
  • Tax calculations were called multiple times while reading the cart, which degraded performance and resulted in excessive charges by external tax calculation services.
  • The handing of unavailable cart items was sub-optimal (see the section below).

The refactoring separated cart calculations from cart contents, which allowed calculations to be invoked only when required. A ShoppingCartPricingSnapshot is created to get pricing and promotions. A ShoppingCartTaxSnapshot is created to calculate taxes. The creation of these snapshots is tied to the resources requested by Cortex clients.

  • Zooming into cart total discount or appliedpromotions links will trigger pricing and promotion calculations.
  • Zooming into the cart order tax link will trigger tax calculations.

When upgrading:

  • You may want to investigate if Cortex clients are invoking pricing, promotion or tax calculations unnecessarily.
  • Shopping cart extension code may require refactoring due to methods being moved from the base cart to pricing or tax snapshots.

Changed handling of unavailable items in the cart

Prior to the current release, an item that had been previously added to the cart but is no longer available disappeared silently from the cart without any opportunity to notify the shopper. This was not an ideal user experience and did not provide projects the flexibility to customize the UX.

For example, a frequently implemented experience is that the item is still visible in the cart with message that it is not available. This gives the shopper an opportunity to decide if they want to replace the item with another similar item or to remove it from the cart.

In the current release:

  • Items that are not available are present in the cart with availability = NOT_AVAILABLE.
  • The user cannot checkout if there are unavailable items in the cart. A needinfo link that points to the item's availability resource is used as the stop condition.

When upgrading:

  • You will need to design and implement the user experience for unavailable cart items.

Changed determination of first-time buyers

Determining whether a customer is a first-time buyer required an expensive query on every Cortex request. This query was eliminated by adding a firstTimeBuyer field to the Customer domain object. The corresponding TCUSTOMER column is created and correctly initialized during the upgrade.

An optional <first-time-buyer> field was added to the Import/Export customers.xml schema, with a default value of false if not specified.

When upgrading:

  • Be aware that upgrading the TCUSTOMER table may be a lengthy process for a large number of customers.

Disabled "Shop on behalf of" functionality by default

Customizations are required for "Shop on behalf of" functionality to work with CMS front ends. Consequently, this functionality has been disabled by default in the Commerce Manager Client.

When upgrading:

  • If you require "Shop on behalf of" functionality, set ENABLE_CREATE_ORDER = true in in the commerce-manager-client project.

Removed Velocity Storefront

The decision to remove the Velocity Storefront aligns with our strategic direction to provide a front-end agnostic commerce platform that powers content management systems and other touchpoints through the Cortex API. See Announcements and Notices for more information.

A shallow removal of storefront functionality was completed in the current release. This involved removing the ep-storefront module from commerce-engine and the ext-storefront module from commerce-extensions. The storefront webapp was also removed from the deployment package and smoketests.

In future releases a deeper removel of storefront functionality is planned which will cleanup orphaned code that was used only by the storefront.

When upgrading:

  • Remove the deleted storefront modules from your projects prior to upgrade. This will make it easier to compare changes between release versions.