Personalized Recommendations API: Request

See also: Response Format

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"

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 complementary or similar touts, 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 tout 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 touts.
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"]
}