Personalized Recommendations API: Request

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

Request Fields

The body of the POST is a single JSON object where each field listed below is an object property. Query parameters will be ignored.

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, see "Using a generated User ID" below.
Example	"3022b347-a272-46c3-b676-62266e335a80"

user

Format	String
Description	The anonymous generated User ID. See "Using a generated User ID" below. If a shopper field is present, this field is ignored.
Example	"3022b347-a272-46c3-b676-62266e335a80"

Using a generated User ID

If the cookie "ssUserId" is currently set, use that.

If if doesn't exist yet, generate a new ID. We recommend using a UUID v4 generator (Such as these examples: JS, PHP, Node). This value should only be generated if it doesn't already exist.

Be sure to set it as the cookie "ssUserId". This must be consistent with the "ssUserId" cookie that you're using for IntelliSuggest event tracking.

cart

Format	String[]
Description	An array of product Skus that are in the current user's cart. Required for real-time personalization functionality.
Example Value	["123-ABC", "567-DEF", "8910-GHI"]

lastViewed

Format	String[]
Description	A array of the 5 most recent product IDs or SKUs whose pages the user has visited. Required for real-time personalization functionality.
Example Value	["123-ABC", "567-DEF", "8910-GHI"]

product

Format	String
Description	The ID or SKU of the product being viewed. Required for profiles that use cross-sell or similar profiles, usually Product Detail Pages.
Example Value	"123-ABC"

tags (Required)

Format	String[]
Description	An array 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"]

categories

Format	String[]
Description	An array of category Ids for use with category-related profiles.
Example Value	["12444"]

Example Request

cURL

curl -X POST https://[siteId].a.searchspring.io/boost/[siteId]/recommend -H 'Content-Type: application/json' -d '{"product": "12345", "shopper": "2bf5adfd-ae44-4ddc-88cb-0d7fa68e7a5c", lastViewed: ["123-ABC","567-DEF","8910-GHI"], "tags": ["also-viewed"]}'

Example Payloads

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

This will improve their personalized experience.

{
	"product": "123-ABC",
	"shopper": "TINAT40777",
	"user": "3022b347-a272-46c3-b676-62266e335a80",
	"cart": ["123-ABC", "567-DEF", "8910-GHI"],
	"lastViewed": ["123-ABC", "567-DEF", "8910-GHI"],
	"tags": ["also-bought"]
}

When the shopper is unknown

{
	"product": "123-ABC",
	"user": "3022b347-a272-46c3-b676-62266e335a80",
	"cart": ["123-ABC", "567-DEF", "8910-GHI"],
	"lastViewed": ["123-ABC", "567-DEF", "8910-GHI"],
	"tags": ["also-bought"]
}