User.com recommender endpoints

User.com recommendations endpoints

Those endpoints are not element of our REST API, so they are open and can be used in front-end implementation, asking for the recommendations in widgets/frames created directly in the browser.

Base URL is your app name, like for: https://appname.user.com/

https://appname.user.com/predictions/predict-for-user

https://appname.user.com/predictions/predict

Response is a JSON, with the array of recommended_products

{

    "recommended_products": [

        {

            "id": 881142,

            "name": "Calvin Klein Obsession",

            "custom_id": "123456",

            "product_url": "https://shop.com/products/calvin-klein-obsession",

          (...)

        }

    ]

}

Endpoint: POST /predictions/predict-for-user

Used to fetch product recommendations for a specific user.

Body Parameters (JSON):

• user_id (string) or user_key (string) — user identifier. Only one of these parameters should be provided. The user_key is usually retrieved from the __ca__chat cookie. In a typical frontend implementation, a fallback value should be provided, such as a default user key that always exists.

• limit (int) — number of recommended products to return, value between 1 and 25.

• segment_id (int, optional) — ID of the product segment from which to prioritize recommendations.

• extra_data (int, optional) — flag (0 or 1) indicating whether to include additional products outside the segment if not enough are found within it (1 = yes, 0 = no).

At least one of user_id or user_key must be provided, but not both.

Example payload:

{
  "user_key": "abc123xyz",
  "limit": 10,
  "segment_id": 456,
  "extra_data": 1
}

Endpoint: POST /predictions/PREDICT

Used to fetch recommendations based on a set of products, without referencing a specific user.

Body Parameters (JSON):

• product_ids (array[integer]) or custom_ids (array[string]) — list of product IDs (system or custom). Only one of these parameters should be provided.

• limit (int) — number of recommended products to return, value between 1 and 25.

• segment_id (int, optional) — ID of the product segment from which to prioritize recommendations.

• extra_data (int, optional) — flag (0 or 1) indicating whether to include additional products outside the segment if not enough are found within it (1 = yes, 0 = no).

At least one of product_ids or custom_ids must be provided, but not both.

Example payload:

{
  "product_ids": [101, 202, 303],
  "limit": 5,
  "segment_id": 123,
  "extra_data": 0
}

Implementation Notes

• In frontend implementations, it is recommended to use user_key retrieved from the __ca__chat cookie.

• A fallback should be provided in case it's missing, e.g., a fixed test user ID.

• Both endpoints support the POST method and require data to be sent in JSON format