In the Searchspring Management Console, configure a Recommendations profile specifying the recommendation strategy (e.g., 'Similar Products', 'Also Viewed') and associate it with a placement (e.g., product detail page).
Call the Recommendations API (GET /api/recommend/products.json) with parameters siteId, product (the current product's ID or URL), userId (from ssUserId cookie), sessionId, and lastViewed (comma-separated recently viewed product IDs); these context parameters enable personalized re-ranking.
The response returns a results array of recommended product objects with relevance scores; render as a carousel below the product description.
Send the userId, sessionId, and pageLoadId on every request — these are required for personalization and reporting to function correctly; read userId from the ssUserId cookie and sessionId from the ssSessionIdNamespace cookie.
If your account includes the Preflight API, call it before the Recommendations request to prime the personalization context, especially when shopper cart contents should influence recommendations.
Known gotchas
The Recommendations API requires siteId, userId, and sessionId — missing any of these causes an error; read cookie values from the Searchspring-managed cookies already set on the domain.
Recommendation profiles are configured in the SMC and are tied to the siteId; changes to a profile are applied on the next API call without a code deploy.
Personalization quality depends on shopper history data — new shoppers with no prior sessions will receive non-personalized fallback recommendations until sufficient interaction history is accumulated.
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp