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.

Personalization

Personalization

Introduction

Personalization refers to offering different pricing, promotions or content based on the shopper's attributes, known as traits. For example, an item's price may only be discounted for shoppers who are over sixty five years old. Personalized pricing is also referred to as Dynamic Pricing or Differential Pricing.

How Personalization Works

Cortex supports personalization of prices and promotions. A shopper's traits are added to a Cortex request in two ways:

  • Cortex automatically infers traits from data in the Commerce Engine or other integrated systems as the request processes.
  • The client application sets traits through the x-ep-user-traits HTTP request header.

Automatically Inferred Traits

When a client application requests a price from Cortex, Cortex evaluates a set of pricing rules using traits inferred from data about the shopper and calculates a corresponding price. The list of traits automatically inferred from the Commerce Engine is shown in the Supported Traits section.

The following diagram summarizes how pricing is affected by shopper's traits inferred from Commerce Engine data:

The client application can also pass additional shopper traits to influence personalization of pricing, promotions and content. See Setting Traits for more information.

Setting Traits

Client applications can pass additional shopper traits to Cortex through the x-ep-user-traits HTTP header. Traits passed through this header override the traits inferred internally by Cortex.

The following diagram summarizes how pricing is affected when a client application passes in a shopper trait:

Using the x-ep-user-traits header is optional. However, if you choose to use the x-ep-user-traits header, you must set it on every request to keep pricing and promotions consistent. Cortex returns the default pricing for any request where the x-ep-user-traits header isn't set, even if the header was previously set in another request.

The x-ep-user-traits HTTP header supports passing multiple traits. Values are a comma-separated list of key/value pairs as outlined in RFC-2616. For example:
x-ep-user-traits: LOCALE=fr-FR, CURRENCY=EUR, GEOIP_COUNTRY_CODE=es ... 
Cortex also accepts multi-line HTTP headers:
x-ep-user-traits: LOCALE=fr
x-ep-user-traits: CURRENCY=EUR
x-ep-user-traits: ...
According to this RFC, x-ep-user-traits values should be wrapped in quotes (") characters if their value contains a comma. This is common for URL values in traits. The header value should look like this:
x-ep-user-traits: "TARGET_URL=http://example.com", GEOIP_COUNTRY_CODE=es

Supported Traits

Out of the box, Cortex supports the traits in the following table. Cortex deployments can be customized to change the set of supported traits by disabling defaults and by adding new custom traits.
Trait Key Type Set Internally Description
LOCALE String Yes The shopper's preferred Locale, declared as an IETF RFC 5646 Language Tag. If the store does not support this Locale, then the store default is used. Cortex does not set this trait by default.
CURRENCY String Yes The shopper's preferred Currency, declared as an ISO 4217 Currency Code. If the store does not support this Currency, then the store default is used. Cortex does not set this trait by default.
SEARCH_TERMS String No A list of terms the shopper used in a search engine to find the e-commerce site. This term must be separated by a ";" semi-colon. Cortex does not set this trait by default.
CUSTOMER_AGE_YEARS Integer Yes The shopper's age in years. Cortex sets this trait by inspecting the shopper's profile and calculating the shopper's age from the shopper's date of birth.
CUSTOMER_GENDER String Yes The shopper's gender. Cortex sets this by inspecting the shopper's profile. Valid values are: F, M.
CUSTOMER_SEGMENT String Yes A list of segments that a shopper belongs to. Multiple segments must be separated by a ";" semi-colon. Cortex sets this trait by inspecting the shopper's assigned segments.
REGISTERED_CUSTOMER Boolean Yes A flag indicating whether the shopper has registered an account. Cortex sets this trait by inspecting the shopper's profile.
INSTORE_SEARCH_TERMS String No A list of terms the shopper used during in-store searches. Terms must be separated by a ";" semi-colon. Cortex does not set this trait by default.
TARGET_URL String No The e-commerce site's landing page URL. Be sure to wrap the key/value pair in quotes.Cortex does not set this trait by default.
REFERRING_URL String No The referring site's URL. Be sure to wrap the key/value pair in quotes.Cortex does not set this trait by default.
FIRST_TIME_BUYER Boolean Yes A flag indicating whether the customer previously made a purchase at this store. Cortex sets this trait by inspecting the shopper's profile.
CATEGORIES_VISITED String No A list of categories the shopper has browsed. Terms must be separated by a ";" semi-colon. Cortex does not set this trait by default.
GEOIP_CONTINENT String No The GeoIP continent.
GEOIP_GMT_TIME_ZONE String No The GeoIP time zone.
GEOIP_FIRST_LEVEL_DOMAIN String No The GeoIP first level domain.
GEOIP_SECOND_LEVEL_DOMAIN String No The GeoIP second level domain.
GEOIP_ZIP_OR_POST_CODE String No The GeoIP zip or postal code.
GEOIP_ROUTING_TYPE String No The GeoIP routing type.
GEOIP_STATE_OR_PROVINCE String No The GeoIP state or province.
GEOIP_CITY String No The GeoIP city.
GEOIP_CONNECTION_TYPE String No The GeoIP connection type.
GEOIP_COUNTRY_CODE String No The GeoIP country code.