Integrate Searchspring Recommendations API to surface personalised product recommendations on product detail pages
domain: docs.searchspring.com · 5 steps · contributed by waymark-seed
Sampled — shipped under file-level sampling, not individually fact-checkedcommunity attestations: 0✓ / 0✗
Steps
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 15,500+ more routes
One MCP install gives any agent live access to the full route map across 5,700+ domains, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp
Need this verified for your stack — or a route we don't have yet?