Skip to main content

​
A

The product ID used as the reference point for similar item recommendations. In refine.recs.similarItems({ anchorId: 'sku_001' }), the anchor is sku_001.
Authentication credential for the Refine API. Obtained from the dashboard. Keep it secret in production environments.

​
C

A collection of products that share a search index. Contains product data, images, and visual embeddings. Identified by a unique catalogId.
Identifier for a recommendation configuration created in the dashboard. Defines which recommendation strategy and parameters to use.
A purchase event tracked via trackPurchase(). Links back to the original search or recommendation that led to the sale.

​
E

A numerical vector representation of a product’s visual features. Generated automatically when products are ingested. Powers visual similarity matching.
A tracked user interaction: impression, click, view, add-to-cart, or purchase. Events power analytics and recommendation improvements.

​
F

A constraint applied to search or recommendation results. Uses operators like eq, gt, in to match product fields.
{ field: 'price', operator: 'lte', value: 100 }
Available operators for filters:
  • eq — equals
  • ne — not equals
  • gt / gte — greater than / greater than or equal
  • lt / lte — less than / less than or equal
  • in / nin — in array / not in array
  • exists — field exists
  • match — text matching
Force-send all queued events immediately. Called via refine.events.flush(). Useful before page unload.

​
I

Link a visitor to a known user account via refine.identify('user_id'). Enables user-based recommendations and cross-session tracking.
When a product is served in search results or recommendations, regardless of whether it was viewed.

​
M

Custom fields on a product beyond standard fields (title, price, image). Stored as key-value pairs, filterable via metadata.fieldName.

​
O

Unique identifier for your Refine organization. Contains multiple catalogs and users. Required for SDK initialization.

​
P

A curated collection of products, often used for category pages. Supports pinned products and intelligent ranking.
SDK extension that adds functionality. Built-in plugins include DebugPlugin, ConsentPlugin, and AutoTrackPlugin.
Zero-indexed location of a product in search results or recommendations. Used in event tracking for click attribution.

​
R

AI-generated product suggestions. Types include similar items, visitor-based, and user-based recommendations.
An error that may succeed if retried. Includes RefineRateLimitError, RefineTimeoutError, RefineServerError, and RefineNetworkError.

​
S

Object returned when tracking served items. Contains methods like trackClick(), trackView(), and trackAddToCart() for subsequent interactions.
Unique identifier for a single serve event (search results or recommendations). Links impressions to subsequent interactions.
Auto-generated identifier for a browsing session. Expires after 30 minutes of inactivity. Retrieved via refine.getSessionId().
Recommendation type that finds products visually and contextually similar to a specified anchor product.
How products were generated (e.g., text-search, image-search, similar-items). Used in event tracking.
Where products are displayed in the UI (e.g., search_results, product_page, home_page). Used in event tracking.

​
T

Search using natural language queries. Combines semantic text understanding with visual similarity matching.
The number of results to return from a search or recommendation request. Common values: 8-48.
The total number of matching products, not limited by topK. Useful for pagination UI (“Showing 24 of 1,847 results”).

​
V

When a product becomes visible to the user (enters the viewport). Tracked via context.trackView().
Auto-generated identifier for an anonymous visitor. Persisted in localStorage. Retrieved via refine.getVisitorId().
Parameter (0.0-1.0) controlling the balance between text and visual search. 0.0 = pure text, 1.0 = pure visual, 0.3 = default.

​
U

Your application’s identifier for a logged-in user. Set via refine.identify('user_id'). Enables personalized recommendations.
Personalized suggestions for identified (logged-in) users based on their full history across sessions and devices.