Einstein Recommendations

The Einstein Recommendations API has two main functions: to receive activities and to output recommendations. Our customers can also achieve flexibility in switching recommenders without any code changes by using our Zone components.

This API documentation is primarily intended for Salesforce Commerce Cloud customers.

To enable access to the Einstein Recommendations API, go to the Einstein Configurator, and input your Commerce Cloud Account Manager client ID in the API page. Using Site Administrator access, you can add an API Client ID on the Account Manager page.

When enabled, and as long as the correct client ID is passed, the API functions in all environments, including production, staging, development, and sandbox instances.

Each API call must pass the x-cq-client-id header for API key authentication.

Implementing our API on the client side or server side comes with some tradeoffs. To ensure that you keep your client ID secret, we recommend that you implement our API on the server side for increased security. Client-side implementation runs the risk of exposing your client ID to bad actors.

The requests to get recommendations, and certain user activities like viewProduct, viewReco, and clickReco, require caching considerations if implemented on the server side. For example, in the case of a user viewing a cached product page, the viewProduct activity should still be sent. It is important that Einstein receives all events, and that recommendations are not cached.

This Einstein Recommendations API is not designed for the email recommendations use case. It does not support embedding Einstein recommendations in emails.

Our service is globally distributed, horizontally scalable, and can automatically scale up and down based on traffic, so load testing is unnecessary. We recommend that you avoid any load testing because it affects recommendation results.

To help generate relevant product recommendations for each shopper, the Einstein Recommendations API provides parameters for shopper identification.

To avoid potential malicious activity, user identifier parameters must be non-sequential. The parameters should not include sequences, patterns, IP addresses, email addresses, names, or anything linked to a specific person. All user identifier parameters must comply with General Data Protection Regulation (GDPR) through hashing or other methods.
  • cookieId (required) - Unique identifier of an anonymous shopper. Typically, the cookieId is the value of a first-party cookie.
    • When making API requests from a traditional Commerce Cloud storefront, pass the cqcid cookie value to match the automatic activity tracking on the traditional storefront. For more information, see Browser-Based Local Data Storage.
    • When using the Salesforce Commerce APIs, pass the USID value available as part of the token retrieval process. For more information, see the Shopper Login and API Access Service documentation.
    • When using OCAPI, pass the visit_id value from the guest login response to match automatic activities. For more information, see the OCAPI Customer Document.
  • userId (encouraged) - Unique identifier of a logged-in shopper. This parameter enables Einstein to link the same logged-in user across multiple devices.
    • When making API requests from a traditional Commerce Cloud storefront, pass the cquid cookie value to match automatic activity tracking on the traditional storefront. For more information, see Browser-Based Local Data Storage.
    • When using the Salesforce Commerce APIs, pass the hashed_login value from the registered login response to match automatic activities. For more information, see the Shopper Login and API Access Service documentation.
    • When using OCAPI, pass the hashed_login value from the registered login response to match automatic activities. For more information, see the OCAPI Customer Document.

Standard performance reporting for recommenders used through the Einstein API is the same as that for other recommenders used on your digital sites. You can view reporting on the Einstein Dashboard (see Einstein Dashboard FAQ to learn more about the Einstein Dashboard).

To make separate reporting and troubleshooting easier, we recommend that you create separate recommenders for the Einstein API. For example, naming a recommender “pdp-mobile-API” indicates that the recommender is used on the product detail page on a mobile app.

Reporting metrics are based on activities. If an application using the Einstein Recommendations API fails to send activities, all metrics for the API recommender appear as zero (0).

Rights of ALBERT EINSTEIN are used with permission of The Hebrew University of Jerusalem. Represented exclusively by Greenlight.