Setup Guide

Prerequisites

Every recipe reads from your project's Live Catalog: the always-fresh copy of your products A vs B keeps as shoppers browse. Set it up once at Set up your product catalog; after that, every recipe uses it automatically. There is no per-recipe "catalog dataset" to pick or link.

On top of the catalog, which prerequisites you need depends on the algorithm:

Order data comes from two sources. If you use the Shopify integration, orders arrive automatically via webhooks, no extra setup. If you use a non-Shopify platform, set up purchase tracking via avsb.track.event() as documented in Tracking Events.

Product-view events for viewed-together work the same way. If you use the Shopify app, the Shopify pixel fires shopify:product_viewed automatically. Without the Shopify app, create a custom event metric in the Metrics page named product_view, then fire it on every product detail page using avsb.track.event(shortId) where shortId is the numeric ID shown on the Metrics page. See Tracking Events for the full calling convention.

Step 1: Set up your Live Catalog

Every recipe reads product details from your project's Live Catalog, so this is the one prerequisite shared by all algorithms. You set it up once (by connecting a server-side source (Shopify, a feed, the Push API, or an upload) and optionally collecting live product data from your storefront as shoppers browse) and from then on it stays current on its own. Follow Connect your catalog, then confirm products are flowing on the Product catalog page.

A few algorithms lean on specific product fields:

• New arrivals orders by each product's source createdAt (falling back to when A vs B first saw the product).
• Similar products matches on title and/or description: at least one is required for a product to be included; richer descriptions give better matches.
• Per-category lists and the Similar products sameCategoryOnly filter use the product's category.
• Turning on excludeOutOfStock uses each product's live availability to keep out-of-stock items out of a recipe. It's off by default.

Step 2: Create a recipe

1. Click New recipe to start.
2. Pick the algorithm that matches your placement. You can't change it after saving.

Step 3: Enable the recipe

Open the recipe's detail page and toggle it enabled. Enabled recipes run nightly at 03:00 UTC. To get results immediately, click Run now. Similar products recipes also start a run automatically the moment you enable them. A catalog change doesn't trigger an immediate run: it's picked up on the next nightly run instead. See Similar Products.

Step 4: Check run status

After a run completes (usually within a few minutes for moderate data volumes), the recipe detail page shows one of three statuses:

• Last run: success: the output dataset has a new live version with fresh results.
• Gathering data: the recipe does not yet have enough events to produce results. The floor is 250 orders (or 250 product-view events for viewed-together) within the recipe's window. New arrivals and Similar products read only the Live Catalog and never show this status. The previous version keeps serving if one exists.
• Last run: failed: something went wrong during the run. The previous version keeps serving. Run stats on the page show the error.

The run stats also show Dropped (no catalog match) (droppedNoCatalog in the API response): the number of items the engine dropped because they had no Live Catalog row. A high number here means your catalog is missing products that your order or browsing history references. Adding those products to the catalog (see Set up your product catalog) will bring coverage up.

Step 5: Test a product

On the recipe detail page, use the Preview panel. For viewed-together, bought-together, and similar-products recipes, search your catalog and pick a product: the panel shows exactly what the recommendations API serves alongside it: real product cards with live price and availability, and which fallback step served. For bestsellers, trending, and new-arrivals recipes there is no product to pick, so just click Preview to see the ranked list.

While a run is in progress (for example, right after you click Run now), the detail page refreshes on its own until the run finishes, so the status and stats update live.

Step 6: Use this recipe on your storefront

The recipe detail page has a Use this recipe panel with the recipe's Feed ID and ready-to-copy code for the three places you can serve it: on a page (window.avsb.recs), inside an experiment variation (options.recs), and on a server (the Node SDK). The Feed ID is the recipe's public handle: you pass it as the recipe value. A recipe only serves while it is enabled.

• Toggle this on to start serving the recipe.
• A green Success badge means the last run finished and the feed has fresh data.
• Copy the Feed ID and pass it as the recipe value wherever you call the recs API.

// Pass the Feed ID shown in the "Use this recipe" panel as `recipe`.const { items } = await window.avsb.recs.get({ recipe: 'rec-homepage-bestsellers' });items.forEach(function renderCard(product) {  // Your own card markup. Each product carries id, title, image, href, price.  var slot = document.querySelector('#recommendations');  if (slot) slot.insertAdjacentHTML('beforeend', '<a href="' + product.href + '">' + product.title + '</a>');});

Reading results in your code

The output dataset works like any other A vs B dataset. The simplest path is to read it from the browser snippet. Wrap the calls in avsb.ready so they are safely queued if the snippet is still loading:

// Your own renderer. Each item carries sku and score plus Live Catalog fields./** @param {unknown[]} items */function renderRecommendations(items) {}// Wrap in avsb.ready: safe to call before the snippet finishes loading.avsb.ready?.(function () {  // For list recipes: look up the global list  avsb.dataset('rec-homepage-bestsellers').get('_global').then(function (result) {    if (!result.found || !result.items?.length) return;    renderRecommendations(result.items);  });  // For viewed-together / bought-together recipes: look up by the product's SKU  var skuEl = document.querySelector('[data-sku]');  var productSku = skuEl && skuEl.getAttribute('data-sku');  if (!productSku) return;  avsb.dataset('rec-pdp-viewed-together').get(productSku).then(function (result) {    if (!result.found || !result.items?.length) return;    renderRecommendations(result.items);  });});

Each item in result.items contains sku and score, plus product details from your Live Catalog (title, image, href, category). The display fields price, compareAtPrice, availability, and stock are resolved live at serve time: price and compareAtPrice arrive as integer minor units with a currency code, so format them for display yourself. See the Reference page for the full row shape.

See Serving & Reading Datasets for the full snippet and Node SDK API.

Configuring a fallback chain

On the recipe detail page, the Fallback chain section shows a drag-and-drop list. Add up to four steps: each step is either another recipe or a dataset. Drag to reorder.

At serve time, the recs API walks the chain whenever the primary recipe has no row for the requested key, serving the first step that can. The final implicit fallback is always the global bestsellers list.

Fine-tuning output with merchandising rules

Once a recipe is running, you can adjust what it shows without touching the algorithm. Merchandising rules let you boost a product's position, demote it, pin it to a fixed slot, or exclude it entirely: per recipe or across all recipes in the project. Rules go live within about a minute; no nightly rebuild needed.

Find them on the recipe's detail page under Merchandising rules. See Merchandising Rules for the full guide.

Testing recipes against each other

Once you have one or more recipes producing output, the natural next question is which one earns more. Run an ordinary experiment whose variation code calls options.recs.get() with a different recipe per variation (or nothing at all, for a holdout), and measure revenue per visitor. See the Recommendations Quickstart for the full walkthrough.