Recommendations Overview

Overview

Refine provides three types of recommendations, each optimized for different use cases:

Type	Best For	Data Required
Similar Items	Product pages, “You may also like”	Anchor product ID
Visitor Recommendations	Homepage, anonymous users	Browsing history (automatic)
User Recommendations	Logged-in users, personalization	User identification

Quick Start

import { Refine } from '@refine-ai/sdk';

const refine = new Refine({
  apiKey: process.env.REFINE_API_KEY,
  organizationId: 'org_abc123',
  catalogId: 'cat_xyz789'
});

// Similar items (product page)
const similar = await refine.recs.similarItems({
  anchorId: 'sku_dress_001',
  topK: 8
});

// Visitor recommendations (homepage, anonymous)
const forVisitor = await refine.recs.forVisitor({
  configId: 'homepage_recs',
  topK: 12
});

// User recommendations (logged-in users)
refine.identify('user_12345');
const forUser = await refine.recs.forUser({
  configId: 'personalized_picks',
  topK: 12
});

Configuration IDs

Visitor and user recommendations require a configId that references a recommendation configuration created in the Refine dashboard. Configurations define:

Strategy — Collaborative filtering, content-based, hybrid
Weighting — Balance between visual similarity and behavioral signals
Filters — Default filters applied to all recommendations
Business rules — Category diversity, price range constraints

Create configurations at: Dashboard → Recommendations → Configurations

Similar items don’t require a configId — they work directly with any product in your catalog.

Tracking Recommendations

Always track when recommendations are served to enable analytics and feedback loops:

const recs = await refine.recs.similarItems({
  anchorId: 'sku_001',
  topK: 8
});

const recsContext = refine.events.trackRecommendations(
  recs.serveId,
  recs.results,
  'product_page',   // surface
  'similar-items',  // source
  { anchorId: 'sku_001' }
);

// Track user interactions
recsContext.trackClick(productId, position);
recsContext.trackView(productId, position);
recsContext.trackAddToCart(productId);

Response Structure

All recommendation methods return the same structure:

interface RecommendationResponse {
  results: RecommendationItem[];
  serveId: string;
  totalResults: number;
}

interface RecommendationItem {
  productId: string;
  title: string;
  price: number;
  imageUrl: string;
  metadata: Record<string, any>;
  score: number;
}

RecommendationItem[]

Array of recommended products, ordered by relevance/score.

string

Unique identifier for this recommendation serve. Used for event tracking.

number

Total number of available recommendations before topK limit.

Filtering Recommendations

Apply filters to narrow recommendations:

const recs = await refine.recs.similarItems({
  anchorId: 'sku_dress_001',
  topK: 8,
  filters: [
    { field: 'price', operator: 'lte', value: 150 },
    { field: 'stock', operator: 'gt', value: 0 },
    { field: 'metadata.category', operator: 'eq', value: 'dresses' }
  ]
});

See Filters for all available operators.

Visual Weight

For similar items, control the balance between visual similarity and other signals:

const recs = await refine.recs.similarItems({
  anchorId: 'sku_001',
  topK: 8,
  visualWeight: 0.7  // High visual similarity emphasis
});

visualWeight	Behavior
`0.0`	Pure metadata/behavioral matching
`0.5`	Balanced (default for most)
`1.0`	Pure visual similarity

Recommendation Strategies by Page

Page	Recommended Type	Configuration
Product Detail Page	Similar Items	`anchorId` = current product
Homepage (anonymous)	Visitor Recs	Popular/trending config
Homepage (logged-in)	User Recs	Personalized config
Cart Page	Similar Items	Multiple anchors from cart
Category Page	Visitor Recs	Category-specific config
Search (no results)	Visitor Recs	Fallback/popular config

Error Handling

import { 
  RefineNotFoundError,
  RefineValidationError 
} from '@refine-ai/sdk';

try {
  const recs = await refine.recs.similarItems({
    anchorId: 'invalid_sku',
    topK: 8
  });
} catch (error) {
  if (error instanceof RefineNotFoundError) {
    // Anchor product doesn't exist
    console.log('Product not found, showing popular items instead');
    return await refine.recs.forVisitor({ configId: 'popular', topK: 8 });
  }
  if (error instanceof RefineValidationError) {
    console.error('Invalid parameters:', error.message);
  }
}

Next Steps

Similar Items

Product-based recommendations

Visitor Recommendations

Anonymous visitor personalization

User Recommendations

Logged-in user personalization

Event Tracking

Track recommendation interactions

Getting Started

SDK

Search