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”.
To ensure the recommendation engine generates relevant and effective suggestions, certain data foundations are crucial.
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.
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”.
More options of product synchronization are described here.
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).
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.
/predictions/predict-for-user/: Delivers personalized recommendations tailored to a specific contact using a user_id or userKey. Link to API docs.
/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.
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.
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:
{
"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
]
}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:
{
"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:
{
"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
}