---
title: "Product Recommendations Technical Setup"
description: "Configure product catalog attributes, event tracking, and API calls to deliver personalized product recommendations in Positive User."
url: https://help.user.com/en/articles/286-product-recommendations-technical-setup
collection: "Product Recommendation Widgets"
updated: 2026-11-03
language: en
alternates: [pl, fr, de, it, es]
---

# Product Recommendations Technical Setup

Configure product catalog attributes, event tracking, and API calls to deliver personalized product recommendations in Positive User.

Product recommendations help your team present personalized suggestions that boost contact engagement and drive online sales. By combining historical purchase data with real-time contact interactions, Positive User predicts which items your contacts want to see next.

Learn how product recommendation models work to get started from “[Introduction to Product Recommendations](https://help.user.com/en/articles/285-introduction-to-product-recommendations.md)”.

## Core Data Requirements

To ensure the recommendation engine generates relevant and effective suggestions, certain data foundations are crucial.

### Product Event Tracking

Consistent and accurate product events tracking is fundamental. Track historical purchase events and real-time contact interactions so the recommendation engine has enough data to learn buying habits and immediate interests.

-   **“Purchase” product event**: Track at least six months of historical purchase event data to establish strong product relationships. Each event sent to Positive User must include the event type (purchase), product ID (custom\_id), and precise timestamp.
    
-   **Other product events**: Track real-time interaction events such as **view**, **add to cart**, and **checkout** with product ID and timestamp. These actions power dynamic suggestions on the `/predictions/predict-for-user/` endpoint.
    

Check the list of available product events [here](https://help.user.com/en/articles/94-what-is-a-product-event.md).

### Product Catalog Attributes

Ensure your catalog items have standard attributes populated so recommendations display complete item details.

Make sure each item includes these standard attributes:

-   **Name**: Display name of the product.
    
-   **Custom\_id**: Unique product identifier matching the ID used in product events.
    
-   **Image\_url**: Direct, publicly accessible link to the product image.
    
-   **Url**: Direct link to the product page on your website.
    
-   **Price**: Current price of the product.
    

You can connect your product feed with the Positive User workspace to have up to date details about the products. More info about it in “[Introduction to Product Feeds](https://help.user.com/en/articles/183-introduction-to-product-feeds.md)”.

More options of product synchronization are described [here](https://apidocs.user.com/docs/guides/ecommerce-integration/product-feed).

## Recommendation API Overview

Select the API endpoint based on whether you want to target specific contacts or show related products. Base URL: `https://<your_workspace_subdomain>.user.com/` (replace <your\_workspace\_subdomain> with your actual workspace subdomain).

> > **Info:** This recommendation API is separate from the standard Positive User REST API and does not require an API authorization key, allowing direct querying from client-side website scripts.

### Recommendation API Endpoints

-   **/predictions/predict-for-user/**: Delivers personalized recommendations tailored to a specific contact using a user\_id or userKey. Link to [API docs](https://apidocs.user.com/docs/guides/product-recommendations/predict-for-user).
    
-   **/predictions/predict/**: Delivers suggestions based on "seed" product IDs (such as items currently in a shopping cart). Use this as a fallback when a contact cannot be identified. Link to [API docs](https://apidocs.user.com/docs/guides/product-recommendations/predict).
    

### API Request Parameters

Send a JSON payload with request parameters to customize which products are returned:

-   **limit**: (number) Maximum number of products to return (maximum 25).
    
-   **user\_id**: (string) Unique customer identifier for logged-in contacts from your website system, matching “custom\_id” in Positive User. Used with `/predictions/predict-for-user/`.
    
-   **userKey**: (string) Positive User system identifier for known and anonymous contacts. Created in the “\_\_ca\_\_chat” cookie when cookie consent is granted and tracking is active. Used with /`predictions/predict-for-user/`.
    
-   **segment\_id**: (number) Numeric ID of a product segment in Positive User (e.g., "All Available Products"). Recommended to keep suggestions restricted to active items.
    
-   **categories**: (array of strings) Filter items by category names (e.g. \['Electronics', 'Laptops'\]).
    
-   **tags**: (array of strings) Filter items by tag names (e.g. \['B2B products', 'Professional products'\]).
    
-   **product\_ids** or **custom\_ids**: (array of numbers or strings) Array of “seed” product IDs for `/predict/` endpoint (maximum 15 IDs per request).
    
-   **extra\_data**: (number: 0 or 1) Controls fallback behavior when filters return fewer products than limit. Set to 0 (Strict Mode) to return only items matching all filters, or 1 (Default) to fill remaining slots with top general recommendations.
    

### API Response

A successful API request returns a JSON response. The core of this response is an object containing a `recommended_products` key, which holds an array of product objects.

Each product object includes standard fields such as:

-   **id**: Positive User system-generated product ID.
    
-   **name**: Product name.
    
-   **custom\_id**: Your product ID.
    
-   **description**: Product description.
    
-   **product\_url**: URL to the product page.
    
-   **image\_url**: URL to the product image.
    
-   **created\_at**, **updated\_at**: Timestamps.
    

Additionally, each product object contains:

-   **attributes array**: Lists all product attributes (standard and custom) defined in Positive User workspace for that product (e.g., “Price”, “Sale\_price”, “Brand”, “Color”, etc). Each attribute has its “Name”, “Value”, and “Value\_type”.
    
-   **categories array**: Lists the categories the product belongs to within Positive User.
    

Example:

```javascript
{
    "recommended_products": [
        {
            "id": 77,
            "name": "Ripped Denim Jacket",
            "custom_id": "1811",
            "description": "This ripped denim jacket...",
            "product_url": "https://ecommerce.demouser.eu/product/ripped-denim-jacket",
            "image_url": "https://ecommerce.demouser.eu/wp-content/uploads/2018/02/6290019144_1_1_1.jpg",
            // ... other standard fields ...
            "attributes": [
                {
                    "name": "price",
                    "name_std": "price",
                    "value": 79.0,
                    "value_type": 7
                },
                // ... other attributes
            ],
            "categories": [
                {
                    "id": 66,
                    "name": "Women, Jackets & Coats"
                }
            ]
        }
        // ... more products
    ]
}
```

## Use Cases

-   **Fetching Personalized Recommendations for a Specific Contact**: Use the `/predictions/predict-for-user/` endpoint with a “userKey” or “user\_id” to display tailored suggestions based on individual browsing habits.
    

Example payload:

```javascript
{
  "userKey": "user_key_value_from_ca_chat_cookie",
  "limit": 5,
  "segment_id": 101 // e.g., "Available Products"
  "extra_data": 0 // Strict: only show items within the segment
}
```

-   **Fetching Recommendations Related to Specific Products**: Use the `/predictions/predict/` endpoint with “custom\_ids” to show related items for products currently in a contact's shopping cart.
    

Example payload:

```javascript
{
  "custom_ids": ["SKU123", "SKU456"], // IDs of products in cart
  "limit": 3,
  "segment_id": 101, // e.g., "Available Products"
  "extra_data": 0 // Strict: only show items within the segment
}
```

## Related Articles

-   [What Is a Product](https://help.user.com/en/articles/135-what-is-a-product.md)
    
-   [What Is a Product Event](https://help.user.com/en/articles/94-what-is-a-product-event.md)
    
-   [Introduction to Product Recommendations](https://help.user.com/en/articles/285-introduction-to-product-recommendations.md)
    
-   [Product Recommendations API Docs](https://apidocs.user.com/docs/guides/product-recommendations/getting-started)
