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]/recommendNOTE: 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
Comments
0 comments
Please sign in to leave a comment.