Skip to main content
Use this guide when launching recommendations into a new surface, such as a homepage feed, related articles rail, product detail page, checkout upsell, video carousel, or email digest.

​
Setup

1

Define the business goal

Decide what the surface should improve: CTR, conversion, AOV, retention, long-tail discovery, editorial coverage, or content freshness.
2

Create a dedicated context

Open Console > Contexts, create a context, and set the recommendation type, model family, and retrieval algorithm.
3

Attach a ranking recipe

Choose a blank recipe, use-case preset, or reference template. Tune candidate sources, signals, discovery, rerank behavior, and guardrails.
4

Review the pipeline

Open the context’s Pipeline tab after saving. Confirm candidate limits, scoring, rules, and post-processing fit the surface.
5

Add filters and rules

Use Advanced for hard pre-query filters. Use the Rules Engine for post-scoring business logic.

​
Validate context behavior in staging

  • Call the Core API recommendation endpoint with the new context_id and representative user IDs.
  • Compare output quality with and without the context applied.
  • Check that the right item categories, availability constraints, and business rules are reflected.
  • Use Explainability to inspect retrieval score, rules, pipeline stages, and feature contributions.
  • Confirm the context’s Currently serving model is the one you expect.

​
Roll out progressively

  • Start with a small traffic segment or internal-only surface.
  • Keep context-specific instrumentation so results can be measured independently.
  • Watch the context’s analytics against the business goal.
  • Increase rollout percentage only after quality checks pass.

​
Keep context docs operational

For each context, maintain a short owner note with:
  • purpose of the surface
  • target KPI
  • attached recipe
  • key filters or rules
  • expected model family
  • rollout status
This makes future recipe, pipeline, and rule changes easier to audit.

​
Example app journey: checkout upsell launch

1

Define upsell objectives

Merchandising defines checkout upsell objectives, such as increasing AOV without recommending unavailable or already-owned items.
2

Create the checkout context

Team creates a checkout context with checkout-safe filters and a conversion-oriented recipe.
3

Review the pipeline

Operators check candidate limits, page size, and whether the rules stage is enabled.
4

Request checkout recommendations

Backend requests recommendations using the checkout context_id during checkout.
5

Tag checkout events

Events are tagged from checkout interactions and posted to /v1/events.
6

Evaluate lift

Analytics is filtered by context to evaluate lift before increasing traffic.

​
Next steps