User.com product recommendations - technical foundations & API

Product recommendations are a vital component for personalizing customer journeys and boosting sales. User.com's recommendation engine leverages user behavior and product data to deliver tailored suggestions, enhancing user experience and driving conversions.

This article delves into the technical underpinnings of the User.com product recommendation system, including data requirements, API endpoints, request configuration, and response handling.

How User.com recommendations work

The User.com recommendation model is primarily pre-trained using historical purchase event data to understand product relationships and general buying patterns.

However, for personalized recommendations, particularly when using the /predictions/predict-for-user/ endpoint, the system also considers the recent product interaction history of the specific user (product events). This includes events like view, add to cart, checkout and others allowing the engine to provide suggestions that are not only based on general trends but also on the user's immediate interests and actions.

Core data requirements

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

Product events tracking

Consistent and accurate product events tracking is fundamental.

• purchase Product Events (essential for model training):

  • Volume: For robust model training, it's recommended to start with historical purchase event data from at least the last six months. Generally, the more data available—and the more varied that data is in terms of products and user interactions—the better the model will perform. While a specific event count can be a secondary indicator, the time range and variety are key.

  • Required event details: Each purchase event sent to User.com must include:

    • event type: purchase

    • product ID: The unique identifier of the product.

    • timestamp: The precise date and time the event occurred.

• Other key Product Events (for enhanced personalization):

  • To leverage real-time user behavior for the /predictions/predict-for-user/ endpoint, tracking additional product-related events is highly recommended. User.com processes specific event names, and providing data for these can significantly enhance personalization. For example, consider tracking events such as:

    • view: Typically sent when a user views a product page.

    • add to cart: Generally used when a user adds a product to their shopping cart.

    • checkout: This event can be sent at various points in the checkout process, for instance, when a user initiates checkout or completes a checkout form. The specific trigger is up to your implementation strategy.

  • Tracking these types of events, along with the purchase history, helps the predict-for-user endpoint deliver more dynamic and contextually relevant recommendations. Each event should include at least the Product ID and Timestamp.

Product catalog attributes

For recommendations to be visually appealing and informative when displayed, your products within the Products section of your User.com app must have key attributes populated:

• name: The display name of the product.

• custom_id: Your unique product identifier, which must match the ID used in product events.

• image_url: A direct, publicly accessible link to the product image.

• url: A direct link to the product's page on your website.

• price: The current price of the product.

You can read more about managing your product catalog in User.com here.

Recommendation API overview

User.com provides API endpoints specifically for fetching product recommendations. The base URL for API calls is: https://<your_app_subdomain>.user.com/ (replace <your_app_subdomain> with your actual application subdomain).

Important note on authorization: This recommendation API is separate from the standard User.com REST API and does not require an API authorization key. This design allows for direct querying from the user's browser, simplifying client-side implementations.

API endpoints

1. /predictions/predict-for-user/

   • Purpose: Delivers personalized recommendations tailored to a specific user.

   • Requires: A user identifier (user_id or userKey).

2. /predictions/predict/

   • Purpose: Provides recommendations based on a specified set of "seed" product IDs (e.g., "products related to what's in the cart," "users who viewed X also viewed Y").

   • Can also serve as a fallback for general recommendations if a specific user cannot be identified by user_id or userKey and you still want to show a recommendation box in the destined placement on your website.

Crafting API requests: configuration parameters

Requests to these endpoints are made by sending a JSON payload. The following parameters allow you to customize the recommendations:

• limit: (number)

  • Maximum number of products to return.

  • Cannot exceed 25.

• user_id: (string)

  • The unique identifier for a user originating from your website's system (e.g., your internal customer ID for a logged-in user). This ID must be the same identifier that is used as the custom_id for that user within your User.com integration to ensure correct matching.

  • Used with /predictions/predict-for-user/.

• userKey: (string)

  • The User.com system identifier for a user (both known and anonymous). When cookie consent is granted and User.com tracking is active on a page a __ca__chat cookie containing this userKey is created for the visitor.

  • Used with /predictions/predict-for-user/.

• segment_id: (number)

  • A numeric ID for a specific product segment defined in User.com (e.g., "All Available Products," "New Arrivals," "On Sale").

  • Highly recommended to filter recommendations to relevant and available products.

  • Usable with both endpoints.

• categories: (array of strings)

  • An array of category names. Only products belonging to these categories will be considered (e.g., ['Electronics', 'Laptops']).

• product_ids or custom_ids: (array of numbers/strings)

  • For /predict/ endpoint: Contains IDs of "seed" products for related recommendations.

  • Use product_ids (User.com system IDs) or custom_ids (your mapped product identifiers).

  • Maximum of 15 product IDs per request to /predict/.

• extra_data: (Number: 0 or 1)

  • Controls behavior when filters (like segment_id, categories, etc.) result in fewer products than the specified limit.

  • If 0 (Strict Mode): Only products strictly matching all provided filters are returned, even if fewer than limit.

  • If 1 (or parameter absent - Default): The recommender attempts to fill the remaining slots with other products generally recommended (e.g., for that user if user_id/userKey is present, or general popular items otherwise), even if those additional items don't strictly match all filters applied to the initial set.

Understanding the API response

A successful API request to either endpoint 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: User.com 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 User.com for that product (e.g., price, sale_price, brand, color). Each attribute has its name, value, and value_type.

• categories array: Lists the categories the product belongs to within User.com.

API response format

{
    "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
    ]
}

Basic endpoint usage scenarios

Here are conceptual examples of how you might structure data for the API endpoints:

Fetching personalized recommendations for a specific user:

• Endpoint: /predictions/predict-for-user/

• Key parameter: userKey (or user_id)

• Example payload idea:

  {
    "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 (e.g., items in cart):

• Endpoint: /predictions/predict/

• Key parameter: custom_ids

• Example payload idea:

  {
    "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
  }

This technical overview should provide a solid foundation for understanding and integrating User.com's product recommendation engine.

Related articles:

• What is Product Feed and how can you add it in User.com?

• Products and their attributes

• Implementing the on-site Recommendation Box with User.com prediction model