Recommender API

Overview

The Recommender API lets you retrieve personalized product suggestions, alternatives, and bestsellers programmatically. It is designed to return recommendation results based on user behavior, item similarity, popularity, and context.

Features

• Flexible batching: Request multiple recommenders in a single API call.
• Context awareness: Restrict recommendations with request-time filters.
• Business logic support: Override settings for scenarios like warehouse-specific availability.

Note

This endpoint is public and requires no authentication.

Tip

To get the best results, synchronize your catalog and integrate analytics so Luigi’s Box can learn user behavior and personalize recommendations.

POST https://live.luigisbox.com/v1/recommend

Request parameters

To get recommendations, send a POST request to the endpoint. The tracker_id is passed as a query parameter and the recommendation definition is 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 batch multiple widgets in one HTTP call.

Parameter	Type	Description
recommendation_type	string	Required. Identifier of the recommender model, for example bestsellers or item_detail_alternatives. See Reference Models.
recommender_client_identifier	string	Arbitrary identifier for the widget location, such as homepage_hero or cart_cross_sell.
user_id	string	User identifier used for personalization. For anonymous users, use a stable client identifier such as the _lb cookie. For logged-in users, use your own customer ID.
item_ids	array	List of item IDs the recommendation should be based on. Required for contextual models such as alternatives or related items. Only the first 10 values are used.
size	integer	Number of items to return. Default: 10. Maximum: 50.
hit_fields	array	List of fields to return for each hit, for example [“title”, “url”, “price”].
blacklisted_item_ids	array	List of item IDs that must be excluded from the response.
recommendation_context	object	Request-time filter object. Supports operators like or, and, not, and range values using the pipe character.
settings_override	object	Overrides model settings for this request, for example changing the availability field in a multi-warehouse setup.
mark_fallback_results	boolean	When true, the response indicates whether a result came from the primary model or a fallback strategy.

Request headers

Header	Value	Required	Description
Content-Type	application/json; charset=utf-8	✓	Indicates JSON request format.
Accept-Encoding	gzip, deflate	Recommended	Enables compressed responses.

Example Request

curl -X POST "https://live.luigisbox.com/v1/recommend?tracker_id=YOUR_TRACKER_ID" \
  -H "Content-Type: application/json" \
  -H "Accept-Encoding: gzip, deflate" \
  -d '[
    {
      "recommendation_type": "item_detail_alternatives",
      "item_ids": ["/products/123"],
      "size": 4
    }
  ]'

How to Make a Request

To make a valid recommendation request:

• Send a POST request to https://live.luigisbox.com/v1/recommend.
• Put tracker_id in the query string.
• Send one or more recommendation request objects in a JSON array.
• Use batching whenever you need recommendations for multiple widgets on the same page.

Code Examples

Ruby

require 'faraday'
require 'json'

connection = Faraday.new(url: 'https://live.luigisbox.com') do |conn|
  conn.use FaradayMiddleware::Gzip
end

payload = [
  {
    "recommendation_type" => "item_detail_alternatives",
    "recommender_client_identifier" => "item_detail",
    "item_ids" => ["/products/123"],
    "size" => 4,
    "user_id" => "user_session_id"
  }
]

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

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

PHP

<?php
require 'vendor/autoload.php';

use GuzzleHttp\Client;

$client = new Client();

$payload = [
    [
        "recommendation_type" => "item_detail_alternatives",
        "recommender_client_identifier" => "item_detail",
        "item_ids" => ["/products/123"],
        "size" => 4,
        "user_id" => "user_session_id"
    ]
];

$response = $client->request('POST', 'https://live.luigisbox.com/v1/recommend', [
    'query' => ['tracker_id' => 'your_tracker_id'],
    'json' => $payload,
    'headers' => [
        'Accept-Encoding' => 'gzip, deflate',
    ],
]);

echo json_encode(json_decode($response->getBody()), JSON_PRETTY_PRINT);

JavaScript

const axios = require('axios');

const payload = [
  {
    recommendation_type: 'item_detail_alternatives',
    recommender_client_identifier: 'item_detail',
    item_ids: ['/products/123'],
    size: 4,
    user_id: 'user_session_id',
  },
];

axios
  .post('https://live.luigisbox.com/v1/recommend', payload, {
    params: { tracker_id: 'your_tracker_id' },
    headers: {
      'Content-Type': 'application/json',
      'Accept-Encoding': 'gzip, deflate',
    },
  })
  .then((response) => {
    console.log(JSON.stringify(response.data, null, 2));
  })
  .catch((error) => {
    console.error(error.message);
  });

Response structure

The response is a JSON array in the same order as the request objects you sent.

Response attributes

Field	Type	Description
recommendation_id	string	Unique identifier for the generated recommendation batch.
recommendation_type	string	Recommender model used for this result set.
recommender_client_identifier	string	Widget identifier echoed from the request.
hits	array	List of recommended items.
hits[].type	string	Usually item.
hits[].url	string	Identity of the recommended product.
hits[].attributes	object	Product data such as title, price, and image fields.
hits[].pinned	boolean	Present when the result was added by customization.
generated_at	string	Generation timestamp.

Example Response

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

Error handling

The API uses standard HTTP status codes to indicate success or failure. All error responses are returned as a JSON array.

Status	Description
200 OK	Success. The body contains recommendation results.
400 Bad Request	Malformed JSON, wrong content type, or missing required parameters.
404 Not Found	The tracker_id or recommendation_type could not be matched.
405 Method Not Allowed	The endpoint only accepts POST requests.
500 Server Error	Internal error. If persistent, contact support.

Error responses

400 Bad Request

[
  {
    "reason": "tracker_id must be filled"
  }
]

404 Not Found

[
  {
    "reason": "Unable to find recommender mapping. Check your tracker_id: 'your-tracker-id' and recommendation types: 'bestsellers'."
  }
]

405 Method Not Allowed

405 Method Not Allowed
The method is not allowed for the requested URL.