Navigation
API v1 API v2

Recommender API V2

Use the Recommender API to retrieve personalized product suggestions, alternatives, and bestsellers.

Overview

Note This endpoint is publicly available and requires no authentication.

The Recommender API allows you to retrieve personalized product suggestions, alternatives, and bestsellers programmatically. It is designed to personalize the user experience by delivering relevant content based on user interaction history, item popularity, and similarity.

Features include:

  • Flexibility: Request different types of recommendations (e.g., alternatives, cross-sells, last viewed) in a single batch.
  • Context Awareness: Filter recommendations dynamically based on the user's current context (e.g., gender, category).
  • Business Logic: Apply availability checks or warehouse-specific logic.

Important To use this feature, you must synchronize your product data and integrate analytics to enable personalization.

POST https://live.luigisbox.tech/v2/recommend

Request Parameters

To get recommendations, send a POST request to the endpoint. The tracker_id is passed as a query parameter, while the specific recommendation details are sent in the JSON body.

Query Parameters

Parameter Type Required Description
tracker_id string ✓ Your unique site identifier within Luigi's Box.

Request Body

The request body is a JSON array of recommendation request objects. This allows you to request multiple different recommendations (batching) in a single HTTP call.

Parameter Type Description
widget_id string Required. Arbitrary ID to tag specific widget locations (e.g., 'homepage_hero', 'cart_cross_sell'). Useful for analytics segmentation.
model string Identifier of the recommender model (e.g., bestsellers, item_detail_alternatives). See Recommender models.
auth_user_id string Logged-in User ID.
The unique identifier of a logged-in user. Required for personalization if the user is logged in.
device_user_id string Anonymous Device ID.
The browser/cookie identifier (e.g., the _lb cookie value). Used to track anonymous sessions or link them to a logged-in profile.
identities array List of item IDs to base recommendations on. Required for contextual models like 'alternatives' or 'related'. Note: Only the first 10 entries are used.
size integer Number of items to return. Default is 10. Maximum is 50.
hit_fields array List of specific fields to retrieve (e.g., ['title', 'url', 'price']).
blocklisted_identities array List of item IDs to explicitly exclude from results.
recommendation_context Array Defines request-time restrictions (filters).
Format: List of objects, each containing attribute, values, and operator.

Examples:
• OR logic: [{"attribute": "gender", "values": ["woman", "unisex"], "operator": "or"}]
• AND logic: [{"attribute": "color", "values": ["black", "blue"], "operator": "and"}]
• NOT logic: [{"attribute": "allergens", "values": ["nuts"], "operator": "not"}]
• Ranges: Use pipe | (e.g., [{"attribute": "price", "values": ["10|50"]}]).

Combined (Multiple Filters):
[ {"attribute": "gender", "values": ["woman"], "operator": "or"}, {"attribute": "brand", "values": ["Nike"], "operator": "not"}, {"attribute": "price", "values": ["|150"]} ]
settings_override object Overrides default settings. Common use case: Multi-warehouse availability.
Example: {'availability_field': 'warehouse_2_availability'}.
mark_fallback_results boolean If true, the response will indicate if a result came from the primary strategy or a fallback.

Request Headers

Header Value
Content-Type application/json; charset=utf-8
Accept-Encoding gzip, deflate (Recommended)

Example Request

curl -X POST "https://live.luigisbox.tech/v2/recommend?tracker_id=YOUR_TRACKER_ID" </span>
     -H "Content-Type: application/json" </span>
     -H "Accept-Encoding: gzip, deflate" </span>
     -d '[
           {
             "model": "item_detail_alternatives",
             "identities": ["/products/123"],
             "size": 4
           }
         ]'

How to make a request

The following examples demonstrate how to send a request to the Recommender API using various languages.

To make a valid recommendation request:

  • Endpoint: POST to https://live.luigisbox.tech/v2/recommend.
  • Authentication: Provide your tracker_id in the URL.
  • Payload: Construct a JSON array containing one or more recommendation objects.
  • Headers: Set Content-Type: application/json and Accept-Encoding: gzip.

Tip If you need recommendations for multiple widgets (e.g., "Similar Products" and "Top Sellers") on the same page, include both objects in the array to fetch them in a single network request.

Example Code

# --- Ruby Example for POST /v2/recommend ---
# Assumes 'faraday' gem is installed


require 'faraday'
require 'json'



LUIGISBOX_HOST = 'https://live.luigisbox.tech'
ENDPOINT_PATH = '/v2/recommend'
TRACKER_ID = 'your_tracker_id'



connection = Faraday.new(url: LUIGISBOX_HOST) do |conn|
  conn.use FaradayMiddleware::Gzip
end



# Define the recommendation request body
payload = [
  {
    "model" => "item_detail_alternatives",
    "widget_id" => "item_detail",
    "identities" => ["/products/123"],
    "size" => 4,
    "auth_user_id" => "user_session_id"
  }
]



response = connection.post(ENDPOINT_PATH) do |req|
  req.params['tracker_id'] = TRACKER_ID
  req.headers['Content-Type'] = 'application/json'
  req.headers['Accept-Encoding'] = 'gzip, deflate'
  req.body = payload.to_json
end



if response.success?
  puts "Recommendations: #{JSON.pretty_generate(JSON.parse(response.body))}"
else
  puts "Error: #{response.status} - #{response.body}"
end

<?php
// PHP Example for POST /v2/recommend
// Assumes Guzzle is installed


require 'vendor/autoload.php';
use GuzzleHttp\Client;



$LUIGISBOX_HOST = 'https://live.luigisbox.tech';
$ENDPOINT_PATH = '/v2/recommend';
$TRACKER_ID = 'your_tracker_id';



$client = new GuzzleHttp\Client();



$payload = [
    [
        "model" => "item_detail_alternatives",
        "widget_id" => "item_detail",
        "identities" => ["/products/123"],
        "size" => 4,
        "auth_user_id" => "user_session_id"
    ]
];



$response = $client->request('POST', "{$LUIGISBOX_HOST}{$ENDPOINT_PATH}", [
    'query' => ['tracker_id' => $TRACKER_ID],
    'json' => $payload,
    'headers' => ['Accept-Encoding' => 'gzip, deflate']
]);



if($response->getStatusCode() == 200) {
    echo json_encode(json_decode($response->getBody()), JSON_PRETTY_PRINT);
} else {
    echo "Error: " . $response->getStatusCode();
}

const axios = require('axios');


// V2 Recommender Request
const LUIGISBOX_HOST = 'https://live.luigisbox.tech';
const ENDPOINT_PATH = '/v2/recommend';
const TRACKER_ID = 'your_tracker_id';



const payload = [
  {
    model: "item_detail_alternatives",
    widget_id: "item_detail",
    identities: ["/products/123"],
    size: 4,
    auth_user_id: "user_session_id"
  }
];



axios.post(LUIGISBOX_HOST + ENDPOINT_PATH, payload, {
  params: { tracker_id: TRACKER_ID },
  headers: {
    'Content-Type': 'application/json',
    'Accept-Encoding': 'gzip, deflate'
  }
})
.then(response => {
  console.log("Recommendations:", JSON.stringify(response.data, null, 2));
})
.catch(error => {
  console.error("Error:", error.message);
});

Response Structure

The response is a JSON array corresponding to the order of the request objects.

Response Attributes

Field Type Description
recommendation_id string Unique ID for the generated recommendation batch.
model string The type of model used (echoed from request).
hits array The list of recommended items.
hits[].type string Usually item.
hits[].identity string The identity of the product.
hits[].attributes object Contains the product data (title, price, image, etc.).
generated_at string Timestamp of generation.

Example Response

[
  {
    "generated_at": "2025-01-13T12:00:00+00:00",
    "recommendation_id": "req-123-abc",
    "model": "item_detail_alternatives",
    "widget_id": "item_detail",
    "hits": [
      {
        "identity": "/products/123456",
        "type": "item",
        "attributes": {
          "title": "Premium Wireless Headphones",
          "price": "199.00 EUR",
          "image_link": "http://myshop.com/imgs/headphones.jpg",
          "availability": "in_stock"
        }
      },
      {
        "identity": "/products/789012",
        "type": "item",
        "attributes": {
          "title": "Standard Wired Headphones",
          "price": "89.00 EUR",
          "image_link": "http://myshop.com/imgs/wired.jpg",
          "availability": "in_stock"
        }
      }
    ]
  }
]

Error Handling

The API uses standard HTTP status codes to indicate success or failure.

HTTP Status

Status Description
200 OK Success. The body contains the recommendation results.
400 Bad Request Malformed JSON or missing required parameters (e.g., tracker_id).
500 Server Error Internal error. If persistent, contact support.

Example Error

{
  "type": "error",
  "message": "Tracker ID is missing"
}