AI Recommendations

Reference for the RecommendationsService class in the Tybrite SDK.

The RecommendationsService class (accessed via client.recommendations) allows you to integrate AI-driven product suggestions into your storefront to increase discovery and conversion.

Secret Key Required. This service requires a Secret Key (sk_live_* / sk_test_*). AI inference is computationally expensive and consumes Gemini API quota — gating to sk prevents abuse from scraped publishable keys. Requests authenticated with a publishable key receive 403 Forbidden.

Methods

getRecommendations

Retrieve curated product suggestions based on various AI models. Use the examples below to see how to implement different recommendation strategies.

Similar Products

// Get products similar in meaning or features to a specific item
const { recommendations } = await client.recommendations.getRecommendations({
  requestBody: {
    type: 'similar',
    productId: 'current-product-uuid',
    limit: 4
  }
});

Recommendation Types Details:

Type	Description	Required Parameters
similar	Products with similar features/meaning (Embedding-based).	productId
also-bought	Products frequently purchased together.	productId
trending	Global trending products (Velocity-based).	-
personalized	Suggestions tailored to a specific user history.	customerId
bundle	Smart bundle suggestions (Semantic + Co-purchase).	productId

Parameters:

Parameter	Type	Description
requestBody	object	Required. The configuration for the recommendation request.
requestBody.type	string	The recommendation algorithm to use.
requestBody.productId	string	Required for similar, also-bought, and bundle.
requestBody.customerId	string	Required for personalized.
requestBody.limit	number	Optional. Maximum number of suggestions to return.

---

Recommendation results are often cached for high performance. The response includes a fromCache boolean, a computedAt ISO timestamp, and an optional fallbackUsed string indicating if the system had to use a simpler algorithm due to data scarcity.

---

Cascading Fallback Chain

When a recommendation type cannot produce results (insufficient data, missing embeddings, cold-start product, etc.), Tybrite degrades gracefully to a simpler algorithm rather than returning an empty array:

Requested Type	Fallback Order
bundle	bundle → also-bought → similar → trending
also-bought	also-bought → similar → trending
similar	similar → trending
personalized	personalized → trending
trending	trending (terminal — no further fallback)

When a fallback is used, the response’s fallbackUsed field contains the name of the algorithm that ultimately produced the results.

---

Response Codes

This endpoint is POST and requires a Secret Key.

Code	Meaning
200	Recommendations returned (possibly via fallback — check fallbackUsed).
400	Invalid type enum or missing required field (productId for similar/also-bought/bundle; customerId for personalized).
401	Invalid or missing API key.
403	Publishable key supplied — recommendations require a Secret Key.
404	productId was provided but the product was not found (applies to similar, bundle, and also-bought).
429	Rate limit exceeded.
500	Internal server error or upstream Gemini failure.