Elevate integration and customerKey guidance
In Elevate, the customerKey is the unique identifier for a visitor on the website. A customerKey is required for every request to the Elevate API, whether for notifications or queries. To link a visitor in Elevate to an Engage contact, the customerKey should be stored in the discoveryKey contact attribute within Engage. This enables cross-platform understanding of the visitor and enhances personalization capabilities for both Elevate and Engage.
Visitor entry
When a visitor enters the site, they may arrive:
Organically
From a referral
Through a newsletter
Flow summary:
If a customerKey is already available (stored client-side or retrieved from softId), use it in all Elevate calls
If no customerKey exists, create one, store it client-side (e.g. in localStorage or in cookie), and then use it in Elevate calls
If a visitor arrives via softId (from an Engage newsletter), decode the softId, retrieve the matching customerKey, and overwrite the local value if it's different
For detailed behavior, see the specific visitor types below.
Visitor identification
Unless the customer is identified at entry (see above), the visitor can be identified during the session by:
Creating an account
Logging in to an existing account
Signing up for a newsletter, wish list, or reminder
Placing an order
Flow summary
When the visitor identifies, check if they exist in Engage.
If not, create the contact and assign discoveryKey = customerKey
If yes, retrieve and compare the discoveryKey to the client’s customerKey
If different, overwrite the client-side customerKey with the Engage discoveryKey.
For detailed behavior, see the specific visitor types below.
Best practices
Ensure Engage is updated with the discoveryKey for all members (visitors who can sign in).
All discoveryKey values must be unique. Duplicate discoveryKey values in Engage prevent personalization.
Always call Elevate with the existing customerKey when a visitor is identified.
Use Engage’s softId for newsletters to maximize identification rate and cross-system linking.
Define a single source of truth for the customerKey, for example the discoveryKey in Engage, to resolve conflicts between local and server values.
Integration flow
New visitor
Step | Action |
|---|---|
The visitor enters |
|
The visitor browses (e.g. category pages, product pages) |
|
The visitor clicks (e.g. navigation links, add to cart, add favorite) |
|
The visitor signs up |
This should create a mapping between the user account, the Elevate customerKey, and the Engage contactId. |
This scenario also covers situations where an unknown visitor makes a purchase and a contact is created in Engage. | |
Returning visitor
Step | Action |
|---|---|
The visitor enters |
|
The visitor browses (e.g. category pages, product pages) |
|
The visitor clicks (e.g. navigation links, add to cart, add favorite) |
|
The visitor signs in |
The visitor is identified, and the existing customerKey from the user account may differ from the customerKey in the cookie. Therefore, it is important to use the customerKey from the user account when calling the Engage API and to update the cookie accordingly. |
Newsletter visitor
Step | Action |
|---|---|
The visitor enters |
|
The visitor browses (e.g. category pages, product pages) |
|
The visitor clicks (e.g. navigation links, add to cart, add favorite) |
|
The visitor signs in |
|