Importing the product catalog
Load items into RecomNext via direct API upserts or scheduled catalog feeds. Configure dimensions, field mapping, freshness, and embedding templates so recommendations, nextQL, and vector search work correctly.
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.
Catalog model
Each item has a stable externalId (your SKU or product ID), an optional top-levelcategory, and a flexible attributes object. Recommendations returnitemId, which matches externalId from ingestion.
| Setting | Type | Default | Description |
|---|---|---|---|
| externalId | string | — | Required. Primary catalog key from your system. |
| category | string | — | Optional. Used in filters, diversity, and fallbacks. |
| attributes | object | — | Price, stock, images, genres, etc. Referenced in nextQL as quoted keys. |
| expiresAt | ISO date | — | Optional. Catalog metadata for expiry; does not auto-delete items. |
Method A — Direct API ingestion
Best for real-time updates, ERP sync, and incremental price or stock changes. Requires API key or HMAC private token — not browser public tokens.
Request
POST https://api.recomnext.com/ingestion/items
Content-Type: application/json
X-Tenant-Id: aurora-games
X-Api-Key: rnx_key_...
{
"items": [
{
"externalId": "game-elden-ring",
"category": "pc",
"attributes": {
"name": "Elden Ring",
"price": 59.99,
"stock": 120,
"genre": ["rpg", "action"],
"featured": true,
"releaseDate": "2022-02-25"
}
},
{
"externalId": "game-hades",
"category": "pc",
"attributes": {
"name": "Hades",
"price": 24.99,
"stock": 0,
"genre": ["roguelike"]
}
}
]
}Response
{ "upserted": 2 }Real-time stock and price sync
Your OMS pushes deltas every few minutes. Upsert only changed SKUs in batches of 100–500. Use a global in-stock rule or scenario filter'stock' > 0 — out-of-stock items remain in catalog for analytics.
await client.ingestion.upsertItems([
{ externalId: 'game-hades', category: 'pc', attributes: { stock: 45, price: 19.99 } },
]);New release day
Add the SKU with rich attributes before marketing goes live. Set featured: true and pair with a booster in the homepage scenario.
Method B — Catalog feeds
Best for nightly or hourly full-catalog sync from a partner API or JSON URL. One active feed per tenant.
| Setting | Type | Default | Description |
|---|---|---|---|
| sourceType | api | json_url | — | Pull from REST API or static JSON URL. |
| itemsPath | JSONPath | — | Path to array of raw items, e.g. $.data |
| itemIdPath | path | — | Field for externalId, e.g. sku |
| mappingRules | array | — | Maps source fields to attributes, category, or semantic targets. |
| pagination | object | — | none, cursor, or limit_offset for large catalogs. |
| scheduleMode | manual | interval | cron | — | When sync runs automatically. |
Example feed configuration
POST https://api.recomnext.com/catalog/feeds
{
"sourceType": "api",
"url": "https://catalog.auroragames.example/v1/products",
"method": "GET",
"itemsPath": "$.data",
"itemIdPath": "sku",
"pagination": {
"mode": "cursor",
"cursorParam": "cursor",
"cursorPath": "$.nextCursor",
"pageSize": 200
},
"mappingRules": [
{ "property": "name", "path": "title", "dataType": "string", "target": "name" },
{ "property": "price", "path": "pricing.usd", "dataType": "double", "target": "basePrice" },
{ "property": "coverUrl", "path": "media.cover", "dataType": "image", "target": "coverImage" },
{ "property": "genre", "path": "tags", "dataType": "enum", "target": "attributes", "facetable": true },
{ "property": "stock", "path": "inventory.available", "dataType": "int", "target": "attributes" }
]
}Workflow: POST /catalog/feeds/:id/preview → activate → sync. Items not seen in a sync can be marked available: false (see availability below).
Multi-region catalog with nested JSON
Map regional price into attributes.price_us and attributes.price_eu. SetfieldMapper.basePricePath to the region you surface in widgets, or include both inincludedProperties when fetching recs.
Dimensions
Dimensions describe attribute metadata for admin UI, faceting, and nextQL discoverability. They do not replace storing values on items — they document what 'genre' or 'platform' means.
PUT https://api.recomnext.com/catalog/tenant-settings
{
"dimensions": [
{
"key": "genre",
"type": "enum",
"label": "Genre",
"facetable": true,
"filterable": true,
"boostable": true,
"source": "manual"
},
{
"key": "platform",
"type": "string",
"label": "Platform",
"filterable": true
}
]
}| Setting | Type | Default | Description |
|---|---|---|---|
| type | enum | string | number | boolean | date | — | How the attribute is interpreted. |
| facetable | boolean | — | Eligible for search facets (with hybrid search). |
| filterable | boolean | — | Shown as filterable in admin and nextQL tooling. |
| boostable | boolean | — | Documented as safe for booster expressions. |
| source | manual | feed | — | feed dimensions can be merged from catalog feed sync. |
Field mapper (mappings)
When your stored JSON is not flat attributes.*, configure paths for admin display and semantic feed targets. This does not change projection paths — use literal document paths in includedProperties.
PUT https://api.recomnext.com/catalog/tenant-settings
{
"fieldMapper": {
"externalIdPath": "attributes.sku",
"namePath": "attributes.title",
"categoryPath": "attributes.platform",
"coverImagePath": "attributes.media.cover",
"basePricePath": "attributes.pricing.usd",
"taxonomyPath": "attributes.taxonomyPath"
}
}| Setting | Type | Default | Description |
|---|---|---|---|
| externalIdPath | path | — | Display identity when not top-level externalId. |
| namePath | path | — | Product title for admin and widgets. |
| coverImagePath | path | — | Primary image URL. |
| basePricePath | path | — | Default price field for cards. |
| taxonomyPath | path | — | Category tree or breadcrumb path. |
Freshness configuration
Freshness tells the engine which attribute represents item age for scenario constraintfreshnessBoostDays (ranking boost, not hard filtering).
{
"freshness": {
"keyPath": "attributes.releaseDate",
"type": "date",
"fallbackToCreatedAt": true
}
}Boost new releases on homepage
Set freshnessBoostDays: 14 on the homepage scenario. Items with release dates in the last 14 days get a scoring boost. For hard cutoffs, add a scenario filter like'releaseDate' > '2026-01-01' (depends on stored format).
Embedding templates
Similar-products and vector search embed item text derived from templates. After upsert, indexing runs asynchronously when a template exists.
| Setting | Type | Default | Description |
|---|---|---|---|
| slug | string | — | Template identifier for category-specific overrides. |
| template | string | — | Format string: {name}, {category}, {description}, plus attribute keys. |
| isDefault | boolean | — | Tenant fallback when no category match. |
| appliesTo | string[] | — | Categories using this template. |
POST https://api.recomnext.com/catalog/embedding-templates
{
"name": "Games default",
"slug": "games-default",
"template": "{name} | {category} | genres: {genre} | {description}",
"isDefault": true,
"appliesTo": []
}Category-specific templates
PC games include platform and genre; DLC items emphasize parent game name. Create templates withappliesTo: ["pc", "console"] for richer vectors on PDP similar-products.
Availability and lifecycle
Distinguish out of stock (attribute, filter with nextQL) from delisted(feed-managed available: false). Recommendations generally exclude unavailable items.
| Setting | Type | Default | Description |
|---|---|---|---|
| attributes.stock | number | — | Business stock; use filters to hide from recs. |
| available | boolean | — | Set false when item missing from feed sync. |
| feedManaged | boolean | — | Item owned by active catalog feed. |