--- schema_version: "1" id: 884087b1ddd4f2b87e45ca40218737001eefc9ca753ba8649855b7e2a6f92433 title: Einstein Recommendations collection: developer version: current locale: en-us portal_url: https://docs.salesforce.com/developer/current/en-us/commerce-cloud/einstein/references/generated-api-specs/einstein-recommendations.md canonical_url: https://developer.salesforce.com/docs/commerce/einstein-api/references/einstein-recommendations source_site: developer.salesforce.com content_type: documentation content_hash: 8bb78ba35b0f6b14828458bd0eff4fd9913156a47138c4ce4f5592872b41f560 products: - B2C Commerce Einstein API - Salesforce APIs --- Einstein Recommendations # Einstein Recommendations ## API Overview The Einstein Recommendations API has two main functions: to receive activities and to output recommendations. For setup and usage information information, see [Einstein Recommendations](https://developer.salesforce.com/docs/commerce/einstein-api/guide/einstein-recommendations-overview.html) in the Guides section. * * * _Rights of ALBERT EINSTEIN are used with permission of The Hebrew University of Jerusalem. Represented exclusively by Greenlight._ **Version:** v3 ## Servers * `https://api.cquotient.com/v3` Protocols: HTTPS. ## /activities (Activities) ## /personalization (Personalization) ## Operations ### POST sendViewProduct `POST /activities/{siteId}/viewProduct` Display name: viewProduct. Tells the Einstein engine when a user opens a product page. #### Parameters * `siteId` (path, EinsteinSiteIdParam, required) * `x-cq-client-id` (header, ClientIdParam, required) #### Request body Media type: `application/json`. Schema: `object`. * `product` (_ProductForView_, required) * `userId` (_UserIdParam_) Application-provided unique identifier for logged in users (hashed). * `cookieId` (_CookieIdParam_) The unique identifier of an anonymous shopper. **If you're making API requests from a traditional B2C Commerce storefront, pass the `dwanonymous_*` cookie value (See [Browser-Based Local Data Storage](https://documentation.b2c.commercecloud.salesforce.com/DOC1/index.jsp?topic=%2Fcom.demandware.dochelp%2FDataProtectionAndPrivacy%2FLocalDataStorage.html&resultof=%22%64%77%61%6e%6f%6e%79%6d%6f%75%73%22%20%22%64%77%61%6e%6f%6e%79%6d%22%20) for more information).** * `clientIp` (_ClientIpParam_) The IP address of the end user. Use this parameter if you're sending activities server-side for a client application. * `clientUserAgent` (_ClientUserAgentParam_) The User Agent of the end user. Use this paramenter if you're sending activities server-side for a client application. * `realm` (_RealmParam_) A unique four-character ID that you can get from your Account Executive (AE) or Customer Success Manager (CSM). The realm is often the first four characters of the Einstein Site ID. However, if your site changes realms in B2C Commerce, the Einstein Site ID won’t use the correct realm. #### Responses * **200** A successful response contains a UUID for the given user. Media type: `application/json`. Schema: `ActivityResponse`. * **400** A validation error response contains an array of invalid parameters. Media type: `application/json`. Schema: `ValidationError`. ### POST sendViewReco `POST /activities/{siteId}/viewReco` Display name: viewReco. Tells the Einstein engine when a user views a set of recommendations. #### Parameters * `siteId` (path, EinsteinSiteIdParam, required) * `x-cq-client-id` (header, ClientIdParam, required) #### Request body Media type: `application/json`. Schema: `object`. * `recommenderName` (_string_, required) The name of the recommender used in the recommendation request. * `__recoUUID` (_string_, required) The UUID that was returned in the recommendation response. * `products` (_array of ProductForView_, required) The recommendations that the user viewed. * `userId` (_UserIdParam_) Application-provided unique identifier for logged in users (hashed). * `cookieId` (_CookieIdParam_) The unique identifier of an anonymous shopper. **If you're making API requests from a traditional B2C Commerce storefront, pass the `dwanonymous_*` cookie value (See [Browser-Based Local Data Storage](https://documentation.b2c.commercecloud.salesforce.com/DOC1/index.jsp?topic=%2Fcom.demandware.dochelp%2FDataProtectionAndPrivacy%2FLocalDataStorage.html&resultof=%22%64%77%61%6e%6f%6e%79%6d%6f%75%73%22%20%22%64%77%61%6e%6f%6e%79%6d%22%20) for more information).** * `clientIp` (_ClientIpParam_) The IP address of the end user. Use this parameter if you're sending activities server-side for a client application. * `clientUserAgent` (_ClientUserAgentParam_) The User Agent of the end user. Use this paramenter if you're sending activities server-side for a client application. * `realm` (_RealmParam_) A unique four-character ID that you can get from your Account Executive (AE) or Customer Success Manager (CSM). The realm is often the first four characters of the Einstein Site ID. However, if your site changes realms in B2C Commerce, the Einstein Site ID won’t use the correct realm. #### Responses * **200** A successful response contains a UUID for the given user. Media type: `application/json`. Schema: `ActivityResponse`. * **400** A validation error response contains an array of invalid parameters. Media type: `application/json`. Schema: `ValidationError`. ### POST sendClickReco `POST /activities/{siteId}/clickReco` Display name: clickReco. Tells the Einstein engine when a user clicks a recommendation. #### Parameters * `siteId` (path, EinsteinSiteIdParam, required) * `x-cq-client-id` (header, ClientIdParam, required) #### Request body Media type: `application/json`. Schema: `object`. * `recommenderName` (_string_, required) The name of the recommender used in the recommendation request. * `__recoUUID` (_string_, required) The UUID that was returned in the recommendation response. * `product` (_ProductForView_, required) * `userId` (_UserIdParam_) Application-provided unique identifier for logged in users (hashed). * `cookieId` (_CookieIdParam_) The unique identifier of an anonymous shopper. **If you're making API requests from a traditional B2C Commerce storefront, pass the `dwanonymous_*` cookie value (See [Browser-Based Local Data Storage](https://documentation.b2c.commercecloud.salesforce.com/DOC1/index.jsp?topic=%2Fcom.demandware.dochelp%2FDataProtectionAndPrivacy%2FLocalDataStorage.html&resultof=%22%64%77%61%6e%6f%6e%79%6d%6f%75%73%22%20%22%64%77%61%6e%6f%6e%79%6d%22%20) for more information).** * `clientIp` (_ClientIpParam_) The IP address of the end user. Use this parameter if you're sending activities server-side for a client application. * `clientUserAgent` (_ClientUserAgentParam_) The User Agent of the end user. Use this paramenter if you're sending activities server-side for a client application. * `realm` (_RealmParam_) A unique four-character ID that you can get from your Account Executive (AE) or Customer Success Manager (CSM). The realm is often the first four characters of the Einstein Site ID. However, if your site changes realms in B2C Commerce, the Einstein Site ID won’t use the correct realm. #### Responses * **200** A successful response contains a UUID for the given user. Media type: `application/json`. Schema: `ActivityResponse`. * **400** A validation error response contains an array of invalid parameters. Media type: `application/json`. Schema: `ValidationError`. ### POST sendAddToCart `POST /activities/{siteId}/addToCart` Display name: addToCart. Tells the Einstein engine when a user adds an item to their cart. #### Parameters * `siteId` (path, EinsteinSiteIdParam, required) * `x-cq-client-id` (header, ClientIdParam, required) #### Request body Media type: `application/json`. Schema: `object`. * `products` (_array of object_, required) The products that the user has added to their cart. * `id` (_string_, required) A unique identifier for the given product. * `sku` (_string_, required) A unique identifier for a sellable unit of the given product, when applicable. * `price` (_number_, required) The discounted or negotiated price of each individual unit of the product. * `originalPrice` (_number_, required) The original price of each individual unit of the product. * `quantity` (_integer_, required) The total number of this item in the cart. * `source` (_SourceParam_) The page or site location where the 'Add To Cart' button was clicked. Accepted values are `pdp`, `plp`, `recs`, `quick add`, and `wishlist`. * `userId` (_UserIdParam_) Application-provided unique identifier for logged in users (hashed). * `cookieId` (_CookieIdParam_) The unique identifier of an anonymous shopper. **If you're making API requests from a traditional B2C Commerce storefront, pass the `dwanonymous_*` cookie value (See [Browser-Based Local Data Storage](https://documentation.b2c.commercecloud.salesforce.com/DOC1/index.jsp?topic=%2Fcom.demandware.dochelp%2FDataProtectionAndPrivacy%2FLocalDataStorage.html&resultof=%22%64%77%61%6e%6f%6e%79%6d%6f%75%73%22%20%22%64%77%61%6e%6f%6e%79%6d%22%20) for more information).** * `clientIp` (_ClientIpParam_) The IP address of the end user. Use this parameter if you're sending activities server-side for a client application. * `clientUserAgent` (_ClientUserAgentParam_) The User Agent of the end user. Use this paramenter if you're sending activities server-side for a client application. * `realm` (_RealmParam_) A unique four-character ID that you can get from your Account Executive (AE) or Customer Success Manager (CSM). The realm is often the first four characters of the Einstein Site ID. However, if your site changes realms in B2C Commerce, the Einstein Site ID won’t use the correct realm. #### Responses * **200** A successful response contains a UUID for the given user. Media type: `application/json`. Schema: `ActivityResponse`. * **400** A validation error response contains an array of invalid parameters. Media type: `application/json`. Schema: `ValidationError`. ### GET getRecommenders `GET /personalization/recommenders/{siteId}` Display name: Recommenders. Get a list of recommenders that can be used in recommendation requests. #### Parameters * `siteId` (path, EinsteinSiteIdParam, required) * `x-cq-client-id` (header, ClientIdParam, required) #### Responses * **200** A successful response will contain a list of recommenders available for use in recommendation requests. Media type: `application/json`. Schema: `RecommendersResponse`. * **400** Either there was no OCAPI client id in the request, or the given OCAPI client id was not valid. Media type: `application/json`. Schema: `ValidationError`. * **403** The given site ID is not valid. Media type: `application/json`. Schema: `ValidationError`. ### POST getRecommendations `POST /personalization/recs/{siteId}/{recommenderName}` Display name: Recommendations. Get a set of recommendations. #### Parameters * `siteId` (path, EinsteinSiteIdParam, required) * `recommenderName` (path, string, required) Name of the recommender to use for recommendations. This item should exist in a response to GET /recommenders for the same site id. * `x-cq-client-id` (header, ClientIdParam, required) #### Request body Media type: `application/json`. Schema: `object`. * `products` (_array of ProductForView_) The products to use as context for generating recommendations. Any given request must have only one of categories or products. When multiple product anchors are sent, recommendations are generated against the first 4 only, reflecting a union of recommendations for each anchor (A-rec1, B-rec1, A-rec2, B-rec2...) with anchors stripped out and recommendations deduped. Exception is Complete the Set Recommender where recommendations reflect whichever single anchor produced the most recommendations. * `categories` (_array of object_) The product categories to use as context for generating recommendations. Any given request must have only one of categories or products. When multiple category anchors are sent, recommendations are generated against the first 4 only, reflecting a union of recommendations for each anchor (A-rec1, B-rec1, A-rec2, B-rec2...) with anchors stripped out and recommendations deduped. * `id` (_string_, required) A unique identifier for the given category. * `rules` (_Rules_) Extra rules to add filtering on the set of recommendations * `userId` (_UserIdParam_) Application-provided unique identifier for logged in users (hashed). * `cookieId` (_CookieIdParam_) The unique identifier of an anonymous shopper. **If you're making API requests from a traditional B2C Commerce storefront, pass the `dwanonymous_*` cookie value (See [Browser-Based Local Data Storage](https://documentation.b2c.commercecloud.salesforce.com/DOC1/index.jsp?topic=%2Fcom.demandware.dochelp%2FDataProtectionAndPrivacy%2FLocalDataStorage.html&resultof=%22%64%77%61%6e%6f%6e%79%6d%6f%75%73%22%20%22%64%77%61%6e%6f%6e%79%6d%22%20) for more information).** * `clientIp` (_ClientIpParam_) The IP address of the end user. Use this parameter if you're sending activities server-side for a client application. * `clientUserAgent` (_ClientUserAgentParam_) The User Agent of the end user. Use this paramenter if you're sending activities server-side for a client application. * `realm` (_RealmParam_, required) A unique four-character ID that you can get from your Account Executive (AE) or Customer Success Manager (CSM). The realm is often the first four characters of the Einstein Site ID. However, if your site changes realms in B2C Commerce, the Einstein Site ID won’t use the correct realm. #### Responses * **200** A successful response will contain a set of recommendations. Media type: `application/json`. Schema: `RecommendationsResponse`. * **400** A request parameter was missing or invalid. Media type: `application/json`. Schema: `ValidationError`. * **404** Either the given `recommenderName` or `siteId` was invalid. Media type: `application/json`. Schema: `ValidationError`. ### POST getZoneRecommendations `POST /personalization/{siteId}/zones/{zoneName}/recs` Display name: Zone Recommendations. Get a set of recommendations for a zone. #### Parameters * `siteId` (path, EinsteinSiteIdParam, required) * `zoneName` (path, string, required) Name of the recommendation zone. * `x-cq-client-id` (header, ClientIdParam, required) #### Request body Media type: `application/json`. Schema: `object`. * `products` (_array of ProductForView_) The products to use as context for generating recommendations. Any given request must have only one of categories or products. When multiple product anchors are sent, recommendations are generated against the first 4 only, reflecting a union of recommendations for each anchor (A-rec1, B-rec1, A-rec2, B-rec2...) with anchors stripped out and recommendations deduped. Exception is Complete the Set Recommender where recommendations reflect whichever single anchor produced the most recommendations. * `categories` (_array of object_) The product categories to use as context for generating recommendations. Any given request must have only one of categories or products. When multiple category anchors are sent, recommendations are generated against the first 4 only, reflecting a union of recommendations for each anchor (A-rec1, B-rec1, A-rec2, B-rec2...) with anchors stripped out and recommendations deduped. * `id` (_string_, required) A unique identifier for the given category. * `rules` (_Rules_) Extra rules to add filtering on the set of recommendations * `userId` (_UserIdParam_) Application-provided unique identifier for logged in users (hashed). * `cookieId` (_CookieIdParam_) The unique identifier of an anonymous shopper. **If you're making API requests from a traditional B2C Commerce storefront, pass the `dwanonymous_*` cookie value (See [Browser-Based Local Data Storage](https://documentation.b2c.commercecloud.salesforce.com/DOC1/index.jsp?topic=%2Fcom.demandware.dochelp%2FDataProtectionAndPrivacy%2FLocalDataStorage.html&resultof=%22%64%77%61%6e%6f%6e%79%6d%6f%75%73%22%20%22%64%77%61%6e%6f%6e%79%6d%22%20) for more information).** * `clientIp` (_ClientIpParam_) The IP address of the end user. Use this parameter if you're sending activities server-side for a client application. * `clientUserAgent` (_ClientUserAgentParam_) The User Agent of the end user. Use this paramenter if you're sending activities server-side for a client application. * `realm` (_RealmParam_, required) A unique four-character ID that you can get from your Account Executive (AE) or Customer Success Manager (CSM). The realm is often the first four characters of the Einstein Site ID. However, if your site changes realms in B2C Commerce, the Einstein Site ID won’t use the correct realm. #### Responses * **200** A successful response will contain a set of recommendations. Media type: `application/json`. Schema: `ZoneResponse`. * **400** A request parameter was missing or invalid. Media type: `application/json`. Schema: `ValidationError`. * **404** Either the given `recommenderName` or `siteId` was invalid. Media type: `application/json`. Schema: `ValidationError`. ## Schemas ### EinsteinSiteIdParam The Einstein Site ID. Locate this ID in the upper-right corner of the [Einstein Configurator](https://configurator.cquotient.com). The ID has the format `xxxx-`. Type: `string`. ### ClientIdParam Make sure to pass the `x-cq-client-id` header with your B2C Commerce Account Manager API Client ID. Locate this value in Business Manager, under Administration > Site Development > Open Commerce API Settings. This settings page displays a JSON object containing the current OCAPI configuration. You can use any of the values in a `client_id` field, but ideally you should create one specifically for Einstein API calls. Type: `string`. ### ProductForView * `id` (_string_, required) A unique identifier for the given product. * `sku` (_string_) A unique identifier for a sellable unit of the given product, where applicable. * `altId` (_string_) An alternate identifier for the given product. You must specify a type in the `altIdType` field. * `altIdType` (_string_) The type of alternate identifier. Allowed values: `vgroup`. ### UserIdParam Application-provided unique identifier for logged in users (hashed). Type: `string`. ### CookieIdParam The unique identifier of an anonymous shopper. **If you're making API requests from a traditional B2C Commerce storefront, pass the `dwanonymous_*` cookie value (See [Browser-Based Local Data Storage](https://documentation.b2c.commercecloud.salesforce.com/DOC1/index.jsp?topic=%2Fcom.demandware.dochelp%2FDataProtectionAndPrivacy%2FLocalDataStorage.html&resultof=%22%64%77%61%6e%6f%6e%79%6d%6f%75%73%22%20%22%64%77%61%6e%6f%6e%79%6d%22%20) for more information).** Type: `string`. ### ClientIpParam The IP address of the end user. Use this parameter if you're sending activities server-side for a client application. Type: `string`. ### ClientUserAgentParam The User Agent of the end user. Use this paramenter if you're sending activities server-side for a client application. Type: `string`. ### RealmParam A unique four-character ID that you can get from your Account Executive (AE) or Customer Success Manager (CSM). The realm is often the first four characters of the Einstein Site ID. However, if your site changes realms in B2C Commerce, the Einstein Site ID won’t use the correct realm. Type: `string`. ### ActivityResponse * `uuid` (_string_, required) The unique identifier for the end user. If you don't already have identifiers associated with a user, you can use this value in subsequent requests. Example: `ce035cc0-2cbb-4d9e-95ed-c67fa55d1eb8`. ### ValidationError * `code` (_string_, required) A short error code to classify types of errors. Example: `ValidationError`. * `errors` (_array of object_, required) A set of invalid parameters. * `location` (_string_, required) The location of the invalid parameter. Example: `body`. * `msg` (_string_, required) A message describing why the parameter is invalid. Example: ``Must provide a `products` array.``. * `param` (_string_, required) The name of the invalid parameter. Example: `products`. * `msg` (_string_, required) A descriptive message about the error that you can use to troubleshoot problems. Example: ``There was a problem validating the request. See `errors`.``. ### SourceParam The page or site location where the 'Add To Cart' button was clicked. Accepted values are `pdp`, `plp`, `recs`, `quick add`, and `wishlist`. Type: `string`. ### RecommendersResponse * `recommenders` (_array of object_, required) The list of available recommenders. Includes all fields of `Recommender`. ### Rules Extra rules to add filtering on the set of recommendations Array of `object`. Each item: A condition that the set of recommendations must meet. A condition that the set of recommendations must meet. * `type` (_string_, required) show, hide, promote, or demote Example: `show`. * `field` (_string_, required) The name of the field to compare. Example: `current_price`. * `operator` (_string_, required) equals, greaterThan, or lessThan. For notEquals, use the opposite rule type (e.g. use a hide rule instead of a show rule). Example: `greaterThan`. * `values` (_array of string | number_, required) The list of values to compare. For greaterThan or lessThan operations, the array should consist of just one number element. _Example_ ``` - 19.99 ``` ### RecommendationsResponse * `recoUUID` (_string_, required) Identifier of this recommendation set. Example: `05e0bd80-64eb-4149-ad5a-dfe1996f8f57`. * `recs` (_array of object_, required) The set of recommendations. Includes all fields of `Recommendation`. ### ZoneResponse * `displayMessage` (_string_) Text to (optionally) use to accompany the given recommendations. This message can be edited in the Configurator. Example: `Recently Viewed`. * `recoUUID` (_string_, required) An identifier of the recommendation set. Example: `05e0bd80-64eb-4149-ad5a-dfe1996f8f57`. * `recs` (_array of object_, required) The set of recommendations. Includes all fields of `Recommendation`. * `recommenderName` (_string_, required) The name of the recommender that was used. Example: `recently-viewed-products`. ### Recommender * `name` (_string_, required) The name of the recommender. Example: `recently-viewed-products`. * `description` (_string_) The description of the recommender. Example: `Recently viewed products.`. * `recommenderType` (_string_, required) The type of the recommender. Example: `recently-viewed`. ### Recommendation * `id` (_string_, required) The ID of the recommendation. Example: `prod_123`. * `product_name` (_string_, required) The name of the recommendation. Example: `Product ABC`. * `product_url` (_string_, required) The product URL of the recommendation. Example: `prod_abc.test.com`. * `image_url` (_string_, required) The image URL of the recommendation. Example: `prod_abc.test.com`.