RecomNext | Recommendation as a Service

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.

Prerequisites

API base URLs

Engine API base URL	Admin UI
https://api.recomnext.com	https://admin.recomnext.com

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

Projection modes

Setting	Type	Default	Description
Default full	mode	—	Omit returnProperties and includedProperties.
Lean	mode	—	returnProperties: false — itemId and score when computed.
Selective	mode	—	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

Setting	Type	Default	Description
Exact paths only	rule	—	attributes.name works; name does not unless top-level exists.
Field mapper	rule	—	Does not apply to includedProperties — catalog paths only.
Missing paths	rule	—	Omitted silently from response.
Unsafe paths	rule	—	__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

Setting	Type	Default	Description
GET recommendations	signing	—	includedProperties as CSV query param before signing.
POST /recommendations	signing	—	Projection keys in JSON body.
POST items-to-items	signing	—	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.