> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kameleoon.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Learn which Product Recommendation API endpoints import your catalog and return recommendations and search results, and how to test them in Postman.

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](https://docs.kameleoon.com/developer-docs/apis/product-recommendation-api-rest/tutorials/import-a-product-catalog-into-kameleoon-using-the-product-recommendation-api.md).

## 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](https://storage.googleapis.com/kameleoon-storage-documentation/developer-docs/downloads/apis/product-recommendation-api-rest/kameleoon-product-recommendation-api.postman_collection.zip) 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.

| Endpoint | Purpose | Reference |
| - | - | - |
| `GET /init` | Starts a session and returns the device ID and session ID. | [Initialize session](https://docs.kameleoon.com/developer-docs/apis/product-recommendation-api-rest/all-endpoints/Initialize/init.md) |
| `POST /import/categories` | Imports your product category hierarchy. | [Import categories](https://docs.kameleoon.com/developer-docs/apis/product-recommendation-api-rest/all-endpoints/Import/import-categories.md) |
| `POST /sync/orders` | Imports or updates transaction orders and their line items. | [Import orders](https://docs.kameleoon.com/developer-docs/apis/product-recommendation-api-rest/all-endpoints/Import/import-orders.md) |
| `PUT /import/products` | Imports or updates your product catalog. | [Import and update products](https://docs.kameleoon.com/developer-docs/apis/product-recommendation-api-rest/all-endpoints/Import/import-product.md) |
| `PATCH /import/products` | Updates the list of in-stock products. | [Update available products](https://docs.kameleoon.com/developer-docs/apis/product-recommendation-api-rest/all-endpoints/Import/update-products.md) |
| `DELETE /import/products` | Deletes products by ID. | [Remove products](https://docs.kameleoon.com/developer-docs/apis/product-recommendation-api-rest/all-endpoints/Import/remove-products.md) |
| `GET /recommend/{recommender_code}` | Returns personalized product recommendations for a recommender block. | [Retrieve product recommendations](https://docs.kameleoon.com/developer-docs/apis/product-recommendation-api-rest/all-endpoints/Recommend/get-recommend.md) |
| `GET /collection/{collection_id}` | Returns a configured product collection and its HTML template. | [Retrieve collection](https://docs.kameleoon.com/developer-docs/apis/product-recommendation-api-rest/all-endpoints/Recommend/get-collection.md) |
| `GET /products` | Returns a filtered list of products. | [Request product list](https://docs.kameleoon.com/developer-docs/apis/product-recommendation-api-rest/all-endpoints/Recommend/get-product-list.md) |
| `GET /search` | Returns instant or full product search results. | [Retrieve search results](https://docs.kameleoon.com/developer-docs/apis/product-recommendation-api-rest/all-endpoints/Search/get-search.md) |

## Guides

Each guide walks you through one task with these endpoints.

* [Import a product catalog](https://docs.kameleoon.com/developer-docs/apis/product-recommendation-api-rest/tutorials/import-a-product-catalog-into-kameleoon-using-the-product-recommendation-api.md): Import categories, products, and availability updates.
* [Modify products in the catalog](https://docs.kameleoon.com/developer-docs/apis/product-recommendation-api-rest/tutorials/modifying-products-in-the-products-catalog.md): Delete products and update their availability.
* [Retrieve product recommendations](https://docs.kameleoon.com/developer-docs/apis/product-recommendation-api-rest/tutorials/retrieving-product-recommendations.md): Display recommendations in your web or mobile app.
* [Retrieve product collections](https://docs.kameleoon.com/developer-docs/apis/product-recommendation-api-rest/tutorials/retrieving-product-collections.md): Display product collections in your web or mobile app.
* [Implement search logic](https://docs.kameleoon.com/developer-docs/apis/product-recommendation-api-rest/tutorials/implement-search-logic-in-your-backend-or-mobile-app.md): Display live and full search results in your backend or mobile app.