RecomNext

Rendering recommendation payloads

Control how much item data returns with each recommendation. Projection uses exact raw document paths. HMAC-signed requests must place projection fields in the correct query or body location.

API base URLs
Engine API base URLAdmin UI
https://api.recomnext.comhttps://admin.recomnext.com

Use the engine base URL as baseUrl in widgets and SDKs.

Projection modes
SettingTypeDefaultDescription
Default fullmode-Omit returnProperties and includedProperties.
Leanmode-returnProperties: false: itemId and score when computed.
Selectivemode-returnProperties: true + includedProperties[]: only listed paths.
Use case
Lean mode for tracking-only rails
{
  "scenario": "homepage-for-you",
  "userId": "customer-42",
  "returnProperties": false
}
Use case
Selective fields for product cards
{
  "scenario": "pdp-similar-pc",
  "itemId": "game-elden-ring",
  "returnProperties": true,
  "includedProperties": [
    "attributes.name",
    "attributes.price",
    "attributes.coverUrl",
    "category"
  ]
}
Path rules
SettingTypeDefaultDescription
Exact paths onlyrule-attributes.name works; name does not unless top-level exists.
Field mapperrule-Does not apply to includedProperties: catalog paths only.
Missing pathsrule-Omitted silently from response.
Unsafe pathsrule-__proto__, constructor, etc. rejected with HTTP 400.

Discover paths: GET https://api.recomnext.com/catalog/items?page=1&limit=1 withX-Tenant-Id.

HMAC signing placement
SettingTypeDefaultDescription
GET recommendationssigning-includedProperties as CSV query param before signing.
POST /recommendationssigning-Projection keys in JSON body.
POST items-to-itemssigning-Projection in body, not query.
# Signed GET: projection is part of the URL
/recommendations/item-to-item/game-elden-ring?scenario=pdp-related&count=8&returnProperties=true&includedProperties=attributes.name,attributes.price

# Signed POST items-to-items: projection in body
POST /recommendations/items-to-items?scenario=cart-upsell
{
  "itemIds": ["game-elden-ring", "game-hades"],
  "returnProperties": true,
  "includedProperties": ["attributes.name", "attributes.price"]
}

GET limits: max 20 included paths, URL length 2048 chars. See API: HMAC notes.

SDK and widgets
// Browser SDK: guard optional score
for (const item of items) {
  const label = item.score != null ? item.score.toFixed(2) : 'N/A';
  console.log(item.itemId, label);
}

Widgets: set data-return-properties and data-included-properties when using lean or selective modes. See Widgets Guide.

Rendering recommendation payloads | RecomNext