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 Cortex API 1.9.0

What's New for Cortex API 1.9.0

Elastic Path Cortex API Version 1.9.0 includes bug fixes, performance improvements, and new features.

If you have any questions, contact Support or go to the Grep community site for the latest information and access to support bulletins, forums, and other Elastic Path resources.

New Features

Recommendations API

A new "recommendations" resource has been added. Items and navigations can return links to additional items of interest, such as "cross-sell" items. This resource currently does not have a CE integration. The SPI interfaces are available, so you can implement your own integration. A sample CSV integration module is available upon request.

Geographies API

A new "geographies" resource has been added and integrated with CE. Geographies returns a list of countries and regions supported for a given scope (CE store). Cortex API client developers can use the resource to build forms, drop-down list boxes, and so on to provide selectors for shipping addresses, new customer addresses, and so on.

Tokenized Payment

Commerce Engine 6.8.0 introduced tokenized payments. Now for CE 6.9.0, purchases can be made through Cortex API using a payment token. A payment token is created for an order through the payment tokens resource. A link to the form is available under the payment method info of an order. If a customer already has a token payment, it will be selected as payment method on order by default. The token display value is viewable in the payment means of the created purchase. For testing, payment tokens for a profile can be created through the "testdefaultpaymenttoken" resource.


Resource Integration SPI Changes

If you customized an integration strategy implementation for any of the following resources, you will need to modify your code to align with the changes.


  • Moved AddressDto from to


  • Removed PostUserAuthenticationStrategy
    • Moved logic to event handlers
  • UserPrincipalLookupStrategy.getUserPrincipal
    • changed parameters from (Collection<String> scopes, String userGuid, Collection<String> roles) to (String userId, Collection<String> scopes, Collection<String> roles)


  • Renamed ItemDto to ItemEntity
    • Renamed property "item correlation id" to "item id"

Item Definitions

  • Interface methods dealing with item options are moved to a separate strategy interface: ItemDefinitonOptionsLookupStrategy. This allows the item definition descriptions (display-name, details) to be sourced outside of CE, while still keeping options sourced by existing CE integrations.

Payment Methods

  • Added PaymentMethodLookupStrategy.isPaymentMethodSelectedForOrder(String scope, String decodedOrderId)
    • Method checks if a payment method is already selected for the order
    • CE integration includes any default payment set to the customer


  • Renamed PriceDto to PriceEntity
    • Removed property "ranged price"
    • moved "ranged price" concept to "from price" on PriceRangeEntity
  • Added ItemPriceLookupStrategy.priceExists(String scope, String decodedItemId)
    • method checks if item has pricing
  • Replaced ItemPriceLookupStrategy.getLowestItemPrice(String scope, String decodedItemId) with ItemPriceLookupStrategy.getItemPriceRange(String scope, String decodedItemId)


  • Instead of returning "FAILED" status purchases, return 409 response
    • Previously, a failed checkout returned a purchase with a FAILED status. Now, Cortex is updated to return a 409 status for failed purchases, instead of returning a purchase with a FAILED status.
  • New PurchaseBillingAddressLookupStrategy in purchases retrieves the purchase billing address
  • Forked PaymentMeansDto into CreditCardPaymentMeansDto and PaymentTokenPaymentMeansDto
    • CreditCardPaymentMeansDto holds all credit card payment info
    • PaymentTokenPaymentMeansDto holds the display value of the payment token


  • Removed PostNewAccountRegistrationStrategy
    • Previously the method was used to apply merge cart logic. Now we use authentication to merge cart, since a user will need to authenticate after registration and this makes more sense to put this logic here.
  • Removed subscription sub-resource from registrations (/registrations/<scope>/subscription)

Multiple Proxy Server Support

This enhancement improves how Cortex API operates when fronted by multiple proxies. Previous Cortex API versions required changes to to work with proxies: Configuring the Cortex API URI

Now, using the setting X-Forwarded-Base in the client's proxy, the href prefixes for the JSON objects returned by the system can be controlled. This allows multiple client developers with different proxies to connect and communicate with Cortex.

Webapp POM Archetype Changes

The Cortex-DCE webapp POM has been split into two POMs: webapp-parent POM and webapp POM. All out-of-the-box dependencies and artifact item definitions that used to live in webapp have been moved to webapp-parent. This change make the webapp POM less cluttered and makes swapping of modules much easier. We recommend that the custom webapp POM should be regenerated with the updated archetypes.

Zoom Improvements

  • Zoom operations are now done concurrently, which has significantly improved load performance.
  • Zoomed objects now start with underscore prefix instead of a colon. This change makes Zoom more compatible with Javascript MVC frameworks. Below is an example of a Zoom response with underscore:
    GET /profiles/mobee/default?zoom=addresses
       self: {
       _addresses: [
             self: {
             links: [
       family-name: "Boxer", 
       given-name: "Ben", 
       links: [

Purchase Billing Address

A "billingaddress" subresource has been added to the purchases resource, allowing a purchase's billing address to be retrieved from /purchases/{scope}/{purchaseId}/billingaddress. Moving billingaddress to the purchases resource is a step towards making addresses a separate resource.

A billing address for a purchase made with a credit cart can still be retrieved the old way, which was through the paymentmeans resource. However, purchases made with a token can only access the purchase's billing address through the purchases resource.

The table below seeks to clarify this:

resource Credit Card Token
purchase O O
paymentmeans O X

Cart Merge During Authentication/Registration

In Cortex 1.7.0, cart merging was performed through the PostUserAuthenticationStrategy and PostNewAccountRegistrationStrategy classes. This tightly coupled the merge cart logic to the registrations and authentication resources. In 1.9.0, we have taken advantage of the OSGi Event Admin service and moved the merge cart logic to event handlers. During authentication, a change event is sent to an events resource, which triggers the event handlers to process the event. This decouples the merge cart logic, making it easier to remove/replace.

This change also removed the merge cart logic from registration.

SubresourceCommand Changed to ReadFromOtherCommand

The SubresourceCommand class has been renamed to ReadFromOtherCommand. Its methods has also been renamed to better describe their purpose. Any custom resource that used SubresourceCommand will need to be updated with the change.

Singleton for Services

All @Named services are now singletons with the @Singleton annotation, with the exception of Command and Command Builder classes. This was to workaround Spring's bug with prototyping where instances were created per invocation. This has removed a lot of overhead and has improved overall start-up time and performance. It is recommended that services extending Cortex API should follow the same pattern.

DynObject Changes

Extending DynObject directly is no longer supported. Also, DynObjects no longer support maps of Entities, where the Map can contain Entities that are automatically adapted to an interface.

In 1.7.0, copying DynObject collections would keep the collection as-is, or make a copy into another collection. The collection would be kept as a Set or a List. Cortex 1.9.0 updates this so that collections are always copied from the source and turned into a List. Stored Collection are now also immutable.

3rd Party Library Changes and Upgrades

Added Dependencies:

  • org.apache.felix.eventadmin-1.3.2

Following are dependencies required by CE to run with its JMS server. Cortex on its own does not support integration with JMS server outside of CE:

  • camel 2.11.1
  • spring-jms 3.1.4

Updated Dependencies:

  • concurrentlinkedhashmap-lru 1.3.2 to 1.4
  • httpclient-osgi 4.2.5 to 4.3.1
  • httpcore-osgi 4.2.5 to 4.3
  • jackson 2.1.4 to 2.3.0
  • javassist 3.17.1-GA to 3.18.1-GA
  • metrics-core 2.1.4 to 3.0.1
  • spring-security-oauth2 1.0.4 to 1.0.5

Environment Changes

Configuration Files


A required configuration file has been added to set the authentication endpoint for Cortex. The file should be located in /etc/ep/cortex/system/config of the server machine. The file should have a DEFAULT_HOST with the value of the /authentication/user full URL, as seen in the below example:


Test Credit Card and Tokenized Payment Configurations

In 1.7.0, a testCreditCard.config file was used to enable/disable the test credit card resource. This file is no longer needed in 1.9.0, as this setting can now be configured directly through the Felix Admin Console. This configuration appears under OSGI > Configuration as "TestCreditResource". The test payment token resource can be configured in the same way with the "TestTokenPaymentResource" configuration.

Known Issues

We found a small issue with our developer environment when importing projects into Eclipse. When you import the cortex webapp project, you may see this error about the maven integration with Eclipse:

"Plugin execution not covered by lifecycle configuration: org.apache.maven.plugins:maven-dependency-plugin:2.8:unpack-dependencies (execution: unpack-configadmin, phase: generate-test-resources)"

To fix the error, include the following maven configuration in your cortex webapp parent pom (see Repository/binaries/com/elasticpath/cortex/dce/ep-cortex-dce-webapp-parent/ of the release):

												<ignore />