Concepts
- Surface — the type of page the shopper is on:
pdp(seed required),plp,cart,home,search,post_purchase,not_found,other. - Placement — a slot on a surface, configured in the dashboard (e.g.
pdp-similar). Each placement sets its strategy chain, product count, rules, size-aware mode and fallback (fill with trending, or hide). - Strategy — how products are chosen:
catalogue,similar,complementary,bought_together,recently_viewed,personalised. Best sellers, new arrivals and trending are orderings applied to a strategy’s results, not separate strategies.
Endpoints
Prerequisites
- Your catalogue is imported into Kleep and at least one placement is configured in the dashboard.
- You have your retailer public id (a UUID, provided by Kleep).
- The Kleep JS library is installed site-wide and gated behind cookie consent.
1. Install the JS library
Before</body>, on every page of your site:
kleep object, which provides:
kleep.getSessionId()— the visitor’s Kleep session id. Pass it to the recommendations API so served recommendations and analytics events join on the same session.kleep.track(event, data)— the analytics calls described in step 4.
kleep.load(...) on product pages as usual — the same library and session serve both features.
2. Fetch recommendations
OnePOST /reco/v1/recommendations per page view returns the products for every placement on the page.
Request
Response
Errors and warnings
Errors come back with a non-2xx status and a JSON body{ "error": { "code", "message", "timestamp", "request_id" } } — USER_INPUT_ERROR (400), RESOURCE_NOT_FOUND (404, unknown retailer), VALIDATION_ERROR (422, failing fields in error.details.validation_errors), INTERNAL_SERVER_ERROR (5xx). Non-fatal conditions keep the 200 and are named in warnings as plain strings (e.g. "fallback trending used to fill results").
Recommendations are never worth a slow page: set a one-second timeout, render the page without the placement when the call fails, and let the next page view try again.
3. Render the placement
Render the products however fits your design — the response carries everything needed for a product card:Respect
hidden: true: it means the placement is configured to disappear rather than show weak results. Render nothing in that case.4. Track analytics events
Analytics close the loop: they tell the dashboard which recommendations were seen, clicked and converted. All events go throughkleep.track — the library stamps them with the session id, user id and page context automatically.
The two recommendation events echo the reco_id from the API response. That is the join key for attribution.
reco_displayed — the placement was seen
Fire once per placement when it becomes visible to the shopper (use an IntersectionObserver rather than firing on render, so below-the-fold placements only count when scrolled into view):
reco_clicked — a recommended product was clicked
Fire when the shopper clicks a product card, before navigating:
Conversion events — the funnel joins itself
The standard commerce events do not take areco_id: send them as usual and Kleep attributes views, add-to-carts and revenue to the placement server-side, by joining reco_clicked with the later commerce events of the same session and product:
Event reference
Field names on recommendation events are
snake_case (reco_id, placement_id, product_ids, product_id, position); camelCase variants are rejected.
Not running the Kleep JS library (native app, server-side)? Manage users and sessions with
POST /reco/v1/users and POST /reco/v1/sessions, and pass the returned session_id as context.session_id. Contact Kleep for the analytics integration in that setup — kleep.track is the attribution channel for web.Feeding the recently_viewed strategy
If a placement uses the recently_viewed strategy, tell Kleep what the shopper views by posting a view event from each product page (the JS library does not send these automatically):
recently_viewed placements on subsequent calls with the same context.session_id.
Complete example
Troubleshooting
- Empty
placementsorhidden: true— the placement has no eligible products for this seed/market and is configured to hide. Check the placement configuration in the dashboard. warningsin the response — non-fatal issues (e.g. a strategy fell back). Log them during integration.- Events not showing in the dashboard — verify the library is loaded (the
kleepobject exists), thatcontext.session_idwas sent on the API call, and thatreco_idon the events matches the API response. Add?debug=trueto the library script URL to see[KLEEP]logs in the console.
