Skip to main content
The Product Recommendation API is a REST API that imports your product catalog into Kameleoon and returns personalized product recommendations and search results to your code. The API is for projects that use the Product Recommendation and Search Personalization add-ons. Your code controls how each product appears, and you can log and debug each call with your own tools.

​
What the API does

The API has four groups of endpoints. Each group covers one part of an integration.
  • Initialize: Start a session to get the device ID and session ID that recommendation and search requests use.
  • Import: Upload categories, products, and orders, update product availability, and remove products.
  • Recommend: Retrieve personalized recommendations for a recommender block, retrieve a product collection, or request a filtered product list.
  • Search: Retrieve instant or full search results for a visitor’s query.

​
Before you begin

  • Add-ons: The API is for projects that use the Product Recommendation and Search Personalization add-ons.
  • Store Key: Find it in Recommendations > Settings > Store settings in the Kameleoon app. Requests send it as shop_id.
  • Secret Key: Find it in the same place. Import requests send it as shop_secret.
Contact your Customer Success Manager for either key if necessary.

​
Import your catalog

Recommendations come from the products in your catalog, so import your data before you request recommendations. Import categories before you upload products, so that the product import uses up-to-date categories. Use the Import and update products endpoint for catalogs with more than 50,000 products, and avoid full catalog re-imports every day. For a lighter change, use the Update available products endpoint to change the availability of existing products. Each import request includes your Secret Key in its body, so send import requests from your backend rather than from a browser or app. For the full import steps, see the catalog import tutorial.

​
How recommendation requests work

Recommendation and search requests use two IDs: the device ID (did) and the session ID (sid). Before you call any other endpoint, call Initialize session to get both.

​
Initialize a session

Start a session to get the device ID and session ID that your other requests need. Send a GET request to https://api.products.kameleoon.com/init with your Store Key as the shop_id query parameter. Call Initialize session at a time that depends on your platform:
  • cURL: Each time your server renders the page.
  • Web: Each time the user opens the page, including in single-page applications.
  • iOS and Android: Each time the app launches.
On the first launch on a new device, call Initialize session without a device ID. The API generates one, and you use it for all later requests. If you call the API from your backend with Web Experimentation, store the session ID in the KameleoonProducts_session_code cookie and the device ID in the KameleoonProducts_device_id cookie.

​
Try the API in Postman

Test Product Recommendation API requests without writing code by using the Kameleoon Product Recommendation API collection in Postman. The collection has one request for each endpoint.
  1. Download the Kameleoon Product Recommendation API collection as a ZIP archive, extract the JSON file, then import it into Postman.
  2. In the collection’s Variables tab, set shopId to your Store Key and shopSecret to your Secret Key. Find both in Recommendations > Settings > Store settings in the Kameleoon app.
  3. Send Initialize session. The request saves the device ID and session ID in the did and sid variables, which the other requests use.
  4. Set recommenderCode or collectionId for the request you want to test, then send it.
The import requests change your product catalog, so check the request body before you send it.

​
API reference

Each endpoint has a reference page with its parameters and examples.

​
Guides

Each guide walks you through one task with these endpoints.