Skip to main content
Your storefront tells Kleep which page the shopper is on and what they are looking at. Kleep returns the products to show in each placement, ranked by the strategy configured in the dashboard, and measures what shoppers do with them.

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.
Placements are created with your Kleep contact in the dashboard. A placement changed in the dashboard applies to the next call, with no storefront release.

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.
Loading the Kleep JS library processes personal data. Legally condition its loading on the visitor’s prior consent to cookies — see Cookies, CMP & Data Privacy. The recommendations API call itself can be made without the library, but the analytics described in this guide require it.

1. Install the JS library

Before </body>, on every page of your site:
The library exposes the global 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.
If you also use Kleep AI Sizing, keep calling kleep.load(...) on product pages as usual — the same library and session serve both features.

2. Fetch recommendations

One POST /reco/v1/recommendations per page view returns the products for every placement on the page.

Request

Key request fields:

Response

Key response fields:

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 through kleep.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):
Fire when the shopper clicks a product card, before navigating:

Conversion events — the funnel joins itself

The standard commerce events do not take a reco_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:
Nothing to carry across pages: as long as reco_clicked is sent on the click, the dashboard attributes the rest of the funnel automatically.

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):
Viewed products are kept per session (most recent first) and feed the shopper’s recently_viewed placements on subsequent calls with the same context.session_id.

Complete example

On the destination product page, track the view as usual — attribution to the clicked placement is joined server-side:

Troubleshooting

  • Empty placements or hidden: true — the placement has no eligible products for this seed/market and is configured to hide. Check the placement configuration in the dashboard.
  • warnings in 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 kleep object exists), that context.session_id was sent on the API call, and that reco_id on the events matches the API response. Add ?debug=true to the library script URL to see [KLEEP] logs in the console.