Frequently bought together

GET /recommendations/frequently-bought-together returns items frequently purchased in the same order as the seed item. Unlike similar (semantic) and also-viewed (browsing), this engine learns from completed transactions.

Request

GET /recommendations/frequently-bought-together?indexId=<id>&itemId=<id>&limit=4
Authorization: Bearer <api-key>

Param	Type	Required	Notes
`indexId`	string	yes	Source index.
`itemId`	string	yes	Seed item.
`limit`	number	no	1–20, default 4. Typical cart UI shows 3–4.

Response

{
  "items": [
    { "id": "sku-9001", "score": 0.73, "data": { ... } }
  ],
  "anchorId": "sku-0001",
  "engine": "frequently-bought-together"
}

score is lift over baseline — 0.73 means this item is 73% more likely to appear in carts containing the seed than in random carts.

When to use

Cart / "Complete the look" — The canonical cart-attach surface.
PDP "Often bought with this" — Inline below the price.
Email — Order-confirmation upsell ("Add to your order — ships in the same box").

Required signal

Needs the order_id field in the analytics event stream to compute co-purchase. Without it, the engine returns an empty array and a Warning: no order_id signal configured header. Configure your storefront connector to emit order_completed events with items: [...].

Latency

p95 ~60 ms on Pro. Precomputed nightly; API is a hash lookup.

Code path

packages/api/modules/recommendations/procedures/frequently-bought-together.ts.