Recommendations Customizations API

Luigi’s Box Recommendations Customizations API allows you to promote specific items by pinning them to defined positions in recommendation results.

To use this feature, a recommender must be initialized. See Recommender API for more details.

!
Warning

We strongly recommend using the Luigi's Box App UI instead of this API. Manage customizations easily at https://app.luigisbox.com/sites/{TRACKER_ID}/setup/recommendations_customization (Luigi's Box App -> Recommendations -> Improvements -> Recommendations customization). It allows you to customize the recommendations with no programming effort. The UI supports CSV / JSON import / export and allows copying customizations across domains.

Customization Overview

Customizations are attached to a specific recommender model (e.g. basket) and include:

  • Scope Target - when customization should apply
  • A list of Pins - what should be returned

Scope Target Types

  • item – Applied when the recommender request input contains a specific item (e.g., /p/123/), priority:3
  • criteria – Applied when the recommender request input matches defined item attributes (e.g., brand = Fender), priority:2
  • all – Applied for all recommendations from a specific model, priority:1

The higher priority means higher importance when dealing with duplicates.

Pin Types

  • item – Pin a specific item (e.g., /p/234/)
  • criteria – Pin items that match certain characteristics (e.g., brand = Fender)
Note

Criteria pins are more computationally expensive and may increase latency.

Pin Behavior

Multiple pins can be used within a single customization. An item can be pinned in multiple customizations. Pins can be:

  • regular: pinned to a specific position.
  • global: pinned to all positions (position = -1).
  • block: used to exclude items (is_block_pin = true and position = 0).

Unavailable or removed items are automatically excluded from results.

Pinned Items Collisions

There are three scenarios that may cause confusion when using recommendation pinning:

  • pins with the same position
  • duplicated items in pins
  • block pin vs regular pin

Pins with the Same Positions

In some cases, multiple different items may be pinned to the same position. When this happens, priority of the scope target type determines which pins are used. All pins with the highest available priority are used, others are ignored.

If multiple recommender request input items match multiple pins of equal priority and position, the pin from the last input item takes precedence. The pins from the preceding items are considered less important and will be placed later.

Duplicated Items in Pins

A single item can appear in multiple pins across various scope targets or positions. The following rules apply:

  • Same pinned item, same scope target: Final position is the minimum of all defined positions.
  • Same pinned item, different scope targets: The pin with the highest priority scope target is kept.

Block Pin vs Regular Pin

You can define both a regular and a block pin for the same item, but with different scope targets. In this case, the regular pin overrides the block pin only if its scope target has a higher priority.

API Specification

Info

This endpoint requires HMAC authentication. Refer to the Authentication section for details.

For full technical details see the OpenAPI Specification.

Get Customizations

POST https://live.luigisbox.com/v1/recommender/pin/{TRACKER_ID}/scopes

Returns a list of existing customizations. Supports filtering, sorting, and pagination.

Optional Parameters

Parameter Description
limitoptional Number of customizations to return.
offsetoptional Number of results to skip.
modeloptional Filter by recommender model.
sortoptional Sort by an attribute (use suffix asc|desc).
tagoptional Filter by tag.
target_identityoptional Filter by target item resource identifier.
target_typeoptional Filter by target type: item, criteria, all.

Sample Response


{
  "pagination": {
    "total": 4
  },
  "results": [
    customization 1,
    customization 2,
    ...
  ]
}

Customization Types

Item


{
  "created_at": "2025-01-22T08:49:58Z",
  "creator": "jon@doe.com",
  "id": "199620b4-df1a-46e8-ab59-9e9ed9af7106", 
  "pin_definitions": [
    pin 1,
    pin 2,
    ...
  ],
  "model": "basket",
  "tags": [
    "black friday", "guitar"
  ],
  "target_identity": "/p/123", 
  "target_metadata": {
    "image_link": "https://doe.com/user/shop/detail/123.jpg?673488c5",
    "title": "Fender Telecaster RW 3",
    "type": "product",
  },
  "target_type": "item"
}

Criteria


{
  "created_at": "2025-01-22T08:49:58Z",
  "creator": "jon@doe.com",
  "id": "199620b4-df1a-46e8-ab59-9e9ed9af7106", 
  "pin_definitions": [
    pin 1,
    pin 2,
    ...
  ],
  "model": "basket",
  "tags": [
    "black friday", "guitar"
  ],
  "target_criteria": criteria,
  "target_type": "criteria"
}

All


{
  "created_at": "2025-01-22T08:49:58Z",
  "creator": "jon@doe.com",
  "id": "199620b4-df1a-46e8-ab59-9e9ed9af7106", 
  "pin_definitions": [
    pin 1,
    pin 2,
    ...
  ],
  "model": "basket",
  "tags": [
    "black friday", "guitar"
  ],
  "target_type": "all"
}

Pin Types

Item

{
  "active_from": "2025-01-22T08:49:58Z",
  "active_to": "2025-04-22T08:49:58Z",
  "available": true,
  "image_link": "https://doe.com/user/shop/detail/234.jpg?482302b8",
  "is_block_pin": false,
  "pin_identity": "/p/234",
  "pin_type": "item",
  "position": 1,
  "title": "guitar case - black"
}

Criteria


{
  "active_from": "2025-01-22T08:49:58Z",
  "active_to": "2025-04-22T08:49:58Z",
  "available": true,
  "is_block_pin": false, 
  "pin_criteria": criteria,
  "pin_type": "criteria"
  "position": 4
}

Criteria Structure

Customization Types target_criteria and Pin Types pin_criteria structure consist of:

Attribute Description
criteriarequired List of criteria that have to be met to apply customization. There are 3 types: Attribute Criteria, Type Criteria and Complex Criteria
operatorrequired Use and if all criteria have to be met, use or if just 1 is required. 
{
  "operator": "and",
  "criteria": [
    {
      "attribute": "gender",
      "operator": "in",
      "values": ["woman", "unisex"]
    },
    {
      "attribute": "size",
      "operator": "lte",
      "values": [38]
    }
  ]
}

Attribute Criteria

Basic criteria covering item attributes.

Attribute Description
attributerequired The name of the attribute which value is used during comparison.
operatorrequired The operation that should be used between attribute value and values.
valuesrequired List of values that are matched against attribute value when evaluating criteria.
conditionoptional The condition that needs to be met. See Criteria Structure - Criteria Condition.
transformationoptional The transformation of the attribute value. See Criteria Structure - Attribute Criteria Transformation

Supported operators for text and boolean attributes:

  • in: An attribute must contain at least one of the provided values.
  • not_in: An attribute cannot contain any of the provided values.
  • all_of: An attribute must contain all the provided values.
  • exists: An attribute must exist. The values are not required.
  • not_exists: An attribute cannot exist. The values are not required.

Supported operators for numeric and date attributes:

  • lt: An attribute must be lower than values.
  • lte: An attribute must be lower than or equal to values.
  • gt: An attribute must be greater than values.
  • gte: An attribute must be greater than or equal to values.
{
  "attribute": "color",
  "operator": "in",
  "values": ["red", "black"]
}

Type Criteria

Special criteria covering item types (product, variant, query, category, article).

Attribute Description
operatorrequired The operation that should be used between item type and values.
valuesrequired List of values that are matched against item type when evaluating criteria.
conditionoptional The condition that needs to be met. See Criteria Structure - Criteria Condition.

Supported operators:

  • in: An item type must be at least one of the provided values.
  • not_in: An item type cannot be any of the provided values.
{
  "operator": "in",
  "values": ["product", "variant"]
}

Complex Criteria

Metaobject allowing to create nested criteria by repeating Criteria Structure. In this way, it is possible to combine groups of criteria with different operators.

{
  "operator": "or",
  "criteria": [
      {
        "attribute": "color",
        "operator": "in",
        "values": ["red", "black"]
      },
      {
        "operator": "and",
        "criteria": [
          {
            "attribute": "gender",
            "operator": "in",
            "values": ["woman", "unisex"]
          },
          {
            "attribute": "size",
            "operator": "lte",
            "values": [38]
          }
        ]
      }
  ]
}

Criteria Condition

Criteria with defined condition are considered only in case, the recommender input validates that condition.

Attribute Description
left_attributerequired The name of the attribute which value is used during criteria validation.
left_valuerequired Item value placeholder referencing which part of the left_attribute value should be used.
operatorrequired An operator that should be used between the left side and the right_values.
right_valuesrequired List of values that are matched against left side when validating criteria.
transformationoptional The transformation of the left_value. See Criteria Structure - Criteria Condition Transformation

Supported operators for text and boolean attributes:

  • in: An attribute must contain at least one of the provided values.
  • not_in: An attribute cannot contain any of the provided values.
  • all_of: An attribute must contain all the provided values.
  • exists: An attribute must exist. The values are not required.
  • not_exists: An attribute cannot exist. The values are not required.

Supported operators for numeric and date attributes:

  • lt: An attribute must be lower than values.
  • lte: An attribute must be lower than or equal to values.
  • gt: An attribute must be greater than values.
  • gte: An attribute must be greater than or equal to values.
  • between: An attribute must be between values range.
  • eq: An attribute must be equal to values.
  • neq: An attribute must not be equal to values.

left_value enables to use value of the left_attribute or its parts. As most attributes of all types contain just 1 value, use:

  • @same - The placeholder represents the exact value of the attribute.

Some text attributes might contain a list of values (e.g. _category, various tags, labels etc). In case of multidimensional lists, requested part of each separate list is returned.

  • @same - The exact value of the attribute.
  • @same_last - Last value of the attribute.
  • @same_first - First value of the attribute.
  • @same_second - Second value of the attribute.
  • @same_third - Third value of the attribute.
  • @same_first_two - First two values of the attribute.
  • @same_first_three - First three values of the attribute.
  • @same_second_and_later - Second and later values of the attribute.
  • @same_third_and_later- Third and later values of the attribute.
  • @same_but_last - All but last value of the attribute.

All of previous also exist in the version with suffix *_main_only (e.g. @same_last_main_only) that allows to return requested part of just first list.

{
  "left_attribute": "_category",
  "left_value": [
    "@same"
  ],
  "operator": "in",
  "right_values": [
    "Apparel", "Shoes", "Jewelry"
  ]
}

Attribute Criteria Transformation

For attribute criteria, it is possible to transform attribute value by defined function.

Attribute Description
functionrequired A The function that is applied to the original attribute value.
valueoptional Parameter of the function.

Supported functions for numeric attributes:

  • +: Add the value to the original attribute value.
  • *: Multiply the value by the original attribute value.

Supported functions for date attributes:

  • +: Add the number of days equal to value to the original attribute value.
{
  "function": "+",
  "value": -5
}

Criteria Condition Transformation

For criteria condition, it is possible to transform left_value by defined function.

Attribute Description
functionrequired A The function that is applied to the original left_value.
valueoptional Parameter of the function.

Supported functions for numeric attributes:

  • +: Add the value to the original left_value.
  • *: Multiply the value by the original left_value.

Supported functions for date attributes:

  • +: Add the number of days equal to value to the original left_value.

Supported functions for text attributes:

  • length: Count the length of left_value. Typically used to count number of categories.
{
  "function": "*",
  "value": 1.2
}

Error Handling

HTTP Status Description
401 Authentication error The request has failed HMAC authentification because it lacks valid credentials to access the requested resource.
404 Not found The server couldn't find the any scope targets.
422 Validation error The request has failed due to invalid request provided.

Get Customizations Summary

GET https://live.luigisbox.com/v1/recommender/pin/{TRACKER_ID}/summary

Returns a histogram of recommender models and their customization counts, plus a list of used tags.

Sample Response

{
  "scope_counts": {
    "basket": 12,
    "basket_popup": 3,
    "item_detail_alternatives": 8,
    "trends": 2
  },
  "user_tags": [
    "black friday",
    "guitar",
    "fender - brand",
    "imported"
  ]
}

Error Handling

HTTP Status Description
401 Authentication error The request has failed HMAC authentification because it lacks valid credentials to access the requested resource.
404 Not found The server couldn't find the any scope targets.

Create Customization

POST https://live.luigisbox.com/v1/recommender/pin/{TRACKER_ID}/scope

Create a new customization with a defined scope and pins list. To add new pins to an existing customization, use the Update Customization endpoint.

Request Body

JSON with the following attributes:

Attribute Description
pin_definitionsrequired List of pin objects. See Pin Format.
modelrequired A recommender model to attach customization to.
target_typerequired Scope target type. One of: item, criteria, all.
tagsoptional List of helper tags to filter customizations by.
target_criteriarequired if target_type: critera Defines conditions under which the pins apply.
target_identityrequired if target_type: item Item resource identifier, for which the pins apply.
target_metadatarequired if target_type: item Metadata of the item (e.g., title, image).

Pin Format

Each pin in pin_definitions is an object with the following:

Attribute Description
active_fromrequired Start date for pin validity.
active_tooptional End date of pin validity.
pin_typerequired One of: item, criteria.
positionrequired Position for the pin. For regular pin set positive integer, for block 0, for global -1.
is_block_pinoptional For block pin set true.
pin_identityrequired if pin_type: item Item resource identifier of a pinned item.
pin_criteriarequired if pin_type: criteria Criteria for selecting matching items. See Criteria Structure.
image_linkrequired if pin_type: item Absolute image URL.
titlerequired if pin_type: item Item title.
placement_idoptional To set pin to a specific placement rather than whole recommender model.

Sample Request

{
  "pin_definitions": [
    {
      "active_from": "2025-01-22T08:49:58Z",
      "image_link": "https://doe.com/user/shop/detail/234.jpg?482302b8",
      "pin_identity": "/p/234",
      "pin_type": "item",
      "position": 1,
      "title": "guitar case - black"
    },
    {
      "active_from": "2025-01-22T08:49:58Z",
      "active_to": "2025-04-22T08:49:58Z",
      "pin_criteria": {
        "operator": "and",
        "criteria": [
          {
            "attribute": "gender",
            "operator": "in",
            "values": ["woman", "unisex"]
          },
          {
            "attribute": "size",
            "operator": "lte",
            "values": [38]
          }
        ]
      },
      "pin_type": "criteria",
      "position": 4
    }
  ],
  "model": "basket",
  "tags": [
    "black friday", "guitar"
  ],
  "target_identity": "/p/123",
  "target_metadata": {
    "image_link": "https://doe.com/user/shop/detail/123.jpg?673488c5",
    "title": "Fender Telecaster RW 3",
    "type": "product"
  },
  "target_type": "item"
}

Error Handling

HTTP Status Description
400 Invalid configuration provided The request has failed due to invalid customization configuration provided.
401 Authentication error The request has failed HMAC authentification because it lacks valid credentials to access the requested resource.
404 Not found The server couldn't find the scope target.
422 Invalid pin definition provided The request has failed due to invalid pin scope provided.

Bulk Create Customizations

POST https://live.luigisbox.com/v1/recommender/pin/{TRACKER_ID}/scopes/_bulk

Creates multiple customizations in one request. Use JSON Lines format (one customization per line). The format follows the Create Customizations endpoint structure.

Error Handling

HTTP Status Description
401 Authentication error The request has failed HMAC authentification because it lacks valid credentials to access the requested resource.
404 Not found The server couldn't find the scope targets.
413 Too many pins provided in a single request The request has failed due to too many pins provided.
422 Invalid pin definition provided The request has failed due to invalid pin definition provided.

Export Customizations

POST https://live.luigisbox.com/v1/recommender/pin/{TRACKER_ID}/scopes/export

Allows to export all customizations for a client. It is possible to filter out expired pins and pins with nonexisting products.

Optional Parameters

Parameter Description
modeloptional Filter by recommender model.
tagoptional Filter by tag.
target_identityoptional Filter by target item resource identifier.
target_typeoptional Filter by target type: item, criteria, all.
remove_expired_pinsoptional Boolean filter of expired pins (active_to < now).
remove_nonexisting_item_pinsoptional Boolean filter of target_identity-ies that no longer exist in the catalog.

Error Handling

HTTP Status Description
401 Authentication error The request has failed HMAC authentification because it lacks valid credentials to access the requested resource.
404 Not found The server couldn't find the any scope targets.
422 Validation error The request has failed due to invalid request provided.

Get Customization by ID

GET https://live.luigisbox.com/v1/recommender/pin/{TRACKER_ID}/scope/<SCOPE_ID>

Retrieves a single customization by its id.

Error Handling

HTTP Status Description
401 Authentication error The request has failed HMAC authentification because it lacks valid credentials to access the requested resource.
404 Not found The server couldn't find the requested scope target.

Update Customization by ID

PUT https://live.luigisbox.com/v1/recommender/pin/{TRACKER_ID}/scope/<SCOPE_ID>

Updates an existing customization by its id using the same JSON body as the Create Customization endpoint.

Error Handling

HTTP Status Description
400 Invalid configuration provided The request has failed due to invalid customization configuration provided.
401 Authentication error The request has failed HMAC authentification because it lacks valid credentials to access the requested resource.
404 Not found The server couldn't find the requested scope target.
422 Invalid pin definition provided The request has failed due to invalid pin scope provided.

Delete customization by ID

DELETE https://live.luigisbox.com/v1/recommender/pin/{TRACKER_ID}/scope/<SCOPE_ID>

Deletes a customization by its id.

Error Handling

HTTP Status Description
401 Authentication error The request has failed HMAC authentification because it lacks valid credentials to access the requested resource.
404 Not found The server couldn't find the requested scope target.