Fetching recommendations
Serve personalized and contextual recommendations via the unified API, Browser SDK, or widgets. Pass a scenario slug to apply filters, boosters, constraints, and segmentation without per-request tuning parameters.
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.
Placement cheat sheet
| Setting | Type | Default | Description |
|---|---|---|---|
| homepage-for-you | user-to-item | — | userId required. Personalized home carousel. |
| pdp-related | item-to-item | — | itemId required. Co-occurrence related items. |
| pdp-similar | similar-products | — | itemId required. Vector similar products. |
| cart-upsell | items-to-items | — | itemIds from cart. Multi-seed recommendations. |
| recently-viewed | recently-viewed | — | userId required. Continue browsing rail. |
Via unified API
POST https://api.recomnext.com/recommendations
Content-Type: application/json
X-Tenant-Id: aurora-games
{
"scenario": "homepage-for-you",
"userId": "customer-42",
"count": 8,
"returnProperties": true,
"includedProperties": [
"attributes.name",
"attributes.price",
"attributes.coverUrl",
"category"
]
}Response
{
"items": [
{
"itemId": "game-elden-ring",
"category": "pc",
"attributes": {
"name": "Elden Ring",
"price": 59.99,
"coverUrl": "https://cdn.auroragames.example/covers/elden.jpg"
},
"score": 0.82
}
],
"count": 8,
"algorithm": "weighted-history"
}Via Browser SDK
const { items } = await recomnext.recommend({
scenario: 'homepage-for-you',
userId: 'customer-42',
count: 8,
includedProperties: ['attributes.name', 'attributes.price', 'attributes.coverUrl'],
});Use case
PDP similar products
const { items } = await recomnext.recommend({
scenario: 'pdp-similar-pc',
itemId: 'game-elden-ring',
count: 6,
});Use case
Cart upsell
const { items } = await recomnext.recommend({
scenario: 'cart-upsell',
itemIds: ['game-elden-ring', 'game-hades'],
userId: 'customer-42',
count: 6,
});Via widgets
<div
data-recomnext-carousel
data-base-url="https://api.recomnext.com"
data-tenant-id="aurora-games"
data-scenario="homepage-for-you"
data-logic="user-to-item"
data-user-id="customer-42"
data-count="8"
data-title="Recommended for you"
data-item-url="/games/{itemId}"
></div>React: Widgets Guide —scenario, logic, renderItem for custom cards.
Legacy GET endpoints
Still supported; unified POST is preferred for consistent projection and POST body signing.
GET https://api.recomnext.com/recommendations/user-to-item/customer-42?scenario=homepage-for-you&count=8
GET https://api.recomnext.com/recommendations/similar-products/game-elden-ring?scenario=pdp-similar&count=6
POST https://api.recomnext.com/recommendations/items-to-items?scenario=cart-upsell
{ "itemIds": ["game-elden-ring", "game-hades"], "count": 6 }Tuning at fetch time
| Setting | Type | Default | Description |
|---|---|---|---|
| scenario | string | — | Applies full scenario config (recommended). |
| count | number | — | Requested items; capped by scenario maxItems. |
| userId | string | — | Required for user-to-item; enables purchase cap on item logic. |
| returnProperties | boolean | true | Full vs lean item payload. |
| includedProperties | string[] | — | Exact raw paths when returnProperties true. |
| noCache | boolean | false | Bypass recommendation cache. |
Filters and boosters are not passed on the request — configure in scenariosand rules.
Building history without scenarios
Personalized user-to-item results improve when you log site-wide behavior, even without tying events to a recommendation placement. Omit scenarioSlug on interactions from search, direct links, and order webhooks.
POST https://api.recomnext.com/ingestion/interactions
{
"interactions": [
{ "userId": "customer-42", "itemId": "game-hades", "type": "view" },
{ "userId": "customer-42", "itemId": "bundle-starter", "type": "purchase" }
]
}See Interactions — without scenario attribution for Browser SDK and batch examples.
Empty results troubleshooting
| Setting | Type | Default | Description |
|---|---|---|---|
| Empty homepage | symptom | — | Cold user — need interactions or wait for popularity blend. |
| Empty similar | symptom | — | Embeddings not indexed — check templates and wait after ingest. |
| Too few items | symptom | — | Strict filters, maxItems, or constraints — relax scenario or enable autoRelax. |
| 401 errors | symptom | — | Token or HMAC signing — see APIs and tokens. |