Personalized Recommendations API: Request

Who can use this feature?
This feature is available on the Expert plan. If you're interested in taking advantage of it, please reach out to your customer success manager. 

See also: Response Format

In order to use personalization features, you must have IntelliSuggest event tracking installed on your site. Be sure to install recommendations tracking as well!

API Endpoint URL

Your Site ID can be found on the My Account page.

https://[siteId].a.searchspring.io/boost/[siteId]/recommend

NOTE: For GET requests, please ensure all characters are URL encoded. It is recommended to ensure requests do not exceed 2,000 characters due to character limits imposed by some browsers.

Request Parameters

Required Parameters

siteId (Required)

Format	String
Description	The unique ID for your site, used in all API requests.
Example	scmq7n

tags (Required)

Format	String
Description	A comma-separated list of profile Ids (tags) from profiles in the management console. The response will include a profile for each tag.
Example Value	also-viewed,also-bought,most-popular

For more information on tags, see the Editing a Profile article. Recommendations profiles must be published before they will be available to the Recommendations API.

For any parameter that expects a comma-separated list, repeated parameters are also allowed. For example, requesting multiple profiles could be accomplished with &tags=also-viewed,also-bought,most-popular or with &tags=also-viewed&tags=also-bought&tags=most-popular

Seed Parameters

product

Format	String
Description	The ID or SKU of the product being viewed. Required for profiles that use cross-sell or similar recommendation types and Recommended for all requests made on Product Detail Pages.
Example Value	987-ZYX

categories

Format	String
Description	A comma-separated list of category Ids. Required when using Category Trending recommendation profiles.
Example Value	182645380

Personalization Parameters

shopper

Format	String
Description	The Id associated with the logged-in shopper on your store. Required for most personalization functionality. If the shopper is anonymous, leave this field out.
Example	3022b347-a272-46c3-b676-62266e335a80

cart

Format	String
Description	A comma-separated list of product SKUs that are in the current user's cart. Required for profiles using the cart cross-sell recommendation type. Required for real-time personalization functionality.
Example Value	123-ABC,567-DEF,8910-GHI

lastViewed

Format	String
Description	A comma-separated list of the 5 most recent product IDs or SKUs whose pages the user has visited. Required for real-time personalization functionality.
Example Value	145-JKL,267-MNO,3910-PQR,467-STU,589-VWX

Additional Parameters

limits

Format	Integer
Description	Limits the number of product recommendations that are returned. When requesting multiple profiles, use a comma-separated list. The limits will be applied in order, corresponding to each profile tag. If a limit is not defined, the default of 20 products will be used.
Default	20
Maximum	20
Example Value	2

Setting the limits parameter to only return the number of recommended products that you want to be available on the page will help to optimize page performance. If no limits are defined, 20 products will be returned for each recommendation profile.

Example Request

When the shopper has logged in, or you know their actual ID

This will improve their personalized experience.

HTTP

https://scmq7n.a.searchspring.io/boost/scmq7n/recommend?product=987-ZYX&shopper=3022b347-a272-46c3-b676-62266e335a80&cart=123-ABC,567-DEF,8910-GHI&lastViewed=145-JKL,267-MNO,3910-PQR,467-STU,589-VWX&tags=also-viewed,also-bought,most-popular&limits=2,3,4

cURL

curl -X GET -G https://scmq7n.a.searchspring.io/boost/scmq7n/recommend -d shopper=3022b347-a272-46c3-b676-62266e335a80 -d cart=123-ABC -d lastViewed=145-JKL,267-MNO,3910-PQR,467-STU,589-VWX -d tags=also-viewed,also-bought,most-popular -d limits=2,3,4

When the shopper is unknown

HTTP

https://scmq7n.a.searchspring.io/boost/scmq7n/recommend?product=987-ZYX&cart=123-ABC,567-DEF,8910-GHI&lastViewed=145-JKL,267-MNO,3910-PQR,467-STU,589-VWX&tags=also-viewed,also-bought,most-popular&limits=2,3,4

cURL

curl -X GET -G https://scmq7n.a.searchspring.io/boost/scmq7n/recommend -d cart=123-ABC -d lastViewed=145-JKL,267-MNO,3910-PQR,467-STU,589-VWX -d tags=also-viewed,also-bought,most-popular -d limits=2,3,4

Common Use Cases

Sample request for Similar recommendations

This example shows what a common request for “Similar” recommendations will look like. These recommendations are often found on Product Details Pages, and can also be referred to as “Customers Also Viewed” or “You May Also Like.”

In this request, the shopper (3022b347-a272-46c3-b676-62266e335a80) is on the PDP for product 987-ZYX, and has three products in their cart (123-ABC,567-DEF,8910-GHI). They’ve already viewed five other products while on the site (145-JKL,267-MNO,3910-PQR,467-STU,589-VWX), which are included in the lastViewed parameter. This request has set a limit of 8 products, since the front-end will display a carousel with 4 products shown and 4 more available for shoppers to page through.

HTTP

https://scmq7n.a.searchspring.io/boost/scmq7n/recommend?product=987-ZYX&shopper=3022b347-a272-46c3-b676-62266e335a80&cart=123-ABC,567-DEF,8910-GHI&lastViewed=145-JKL,267-MNO,3910-PQR,467-STU,589-VWX&tags=similar&limits=8

cURL

curl -X GET -G https://scmq7n.a.searchspring.io/boost/scmq7n/recommend -d shopper=3022b347-a272-46c3-b676-62266e335a80 -d cart=123-ABC,567-DEF,8910-GHI -d lastViewed=145-JKL,267-MNO,3910-PQR,467-STU,589-VWX -d tags=similar -d limits=8

Sample request for multiple recommendation profiles

This example shows how to request multiple recommendations profiles for display on a single page. It is recommended to use a single API request for multiple profiles to decrease latency and to ensure that the same product is not recommended multiple times. In this example, Similar recommendations are shown alongside Cross-Sell recommendations and Recently Viewed recommendations.

In this request, the shopper (3022b347-a272-46c3-b676-62266e335a80) is on the PDP for product 987-ZYX, and has three products in their cart (123-ABC,567-DEF,8910-GHI). They’ve already viewed five other products while on the site (145-JKL,267-MNO,3910-PQR,467-STU,589-VWX), which are included in the lastViewed parameter. This request has set a limit of 8 products for each profile, since the front-end will display carousels with 4 products shown and 4 more available for shoppers to page through.

HTTP

https://scmq7n.a.searchspring.io/boost/scmq7n/recommend?product=987-ZYX&shopper=3022b347-a272-46c3-b676-62266e335a80&cart=123-ABC,567-DEF,8910-GHI&lastViewed=145-JKL,267-MNO,3910-PQR,467-STU,589-VWX&tags=similar,cross-sell,recently-viewed&limits=8,8,8

cURL

curl -X GET -G https://scmq7n.a.searchspring.io/boost/scmq7n/recommend -d shopper=3022b347-a272-46c3-b676-62266e335a80 -d cart=123-ABC,567-DEF,8910-GHI -d lastViewed=145-JKL,267-MNO,3910-PQR,467-STU,589-VWX -d tags=similar,cross-sell,recently-viewed -d limits=8,8,8

Sample request for Cross-Sell recommendations on the Basket page

This example shows what a common request for “Cross-Sell” recommendations will look like when implemented on a Basket (or Cart) page. This recommendation type is intended to display complementary products to be purchased with the products already in the shopper’s cart, meaning that correctly populating the cart parameter is critical.

In this request, the shopper (3022b347-a272-46c3-b676-62266e335a80) has three products in their cart (123-ABC,567-DEF,8910-GHI). They’ve already viewed five other products while on the site (145-JKL,267-MNO,3910-PQR,467-STU,589-VWX), which are included in the lastViewed parameter. This request has set a limit of 10 products for this profile, since the front-end will display carousels with 5 products shown and 5 more available for shoppers to page through.

HTTP

https://scmq7n.a.searchspring.io/boost/scmq7n/recommend?shopper=3022b347-a272-46c3-b676-62266e335a80&cart=123-ABC,567-DEF,8910-GHI&lastViewed=145-JKL,267-MNO,3910-PQR,467-STU,589-VWX&tags=cart-cross-sell&limits=10

cURL

curl -X GET -G https://scmq7n.a.searchspring.io/boost/scmq7n/recommend -d cart=123-ABC,567-DEF,8910-GHI -d lastViewed=145-JKL,267-MNO,3910-PQR,467-STU,589-VWX -d tags=cart-cross-sell -d limits=10

Sample request for Session recommendations on the No Results page

This example shows what a common request for “Session” recommendations will look like when implemented on a No Results page. These recommendations are personalized based on the recent activity of the shopper, so including the lastViewed and cart products is essential. If a shopper is brand new and has yet to view any products, these parameters should be omitted and the recommendations engine will gracefully fall back to trending products.

In this request, the shopper (3022b347-a272-46c3-b676-62266e335a80) has three products in their cart (123-ABC,567-DEF,8910-GHI). They’ve already viewed five other products while on the site (145-JKL,267-MNO,3910-PQR,467-STU,589-VWX), which are included in the lastViewed parameter. This request has set a limit of 10 products for this profile, since the front-end will display carousels with 5 products shown and 5 more available for shoppers to page through.

HTTP

https://scmq7n.a.searchspring.io/boost/scmq7n/recommend?shopper=3022b347-a272-46c3-b676-62266e335a80&cart=123-ABC,567-DEF,8910-GHI&lastViewed=145-JKL,267-MNO,3910-PQR,467-STU,589-VWX&tags=no-results&limits=10

cURL

curl -X GET -G https://scmq7n.a.searchspring.io/boost/scmq7n/recommend -d cart=123-ABC,567-DEF,8910-GHI -d lastViewed=145-JKL,267-MNO,3910-PQR,467-STU,589-VWX -d tags=no-results -d limits=10