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;
}
Array of recommended products, ordered by relevance/score.
Unique identifier for this recommendation serve. Used for event tracking.
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' }
]
});
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
