Frequently-Bought-Together Recommendations

Paid pluginsize Mplanned, not built

Indicative price, not an offer: $19-39/mo

Generated from docs/plan/paid/frequently-bought-together-recommendations/PLAN.md in the AstroBaaS repository. Nothing described below is implemented — it is the written plan for it.

A paid module that analyzes historical order data to identify product pairs and triplets that sell together frequently. It surfaces these bundles on product detail pages with a recommendation widget, A/B tests different recommendation sets, and tracks the AOV lift to help merchants optimize product placement and bundling.

The problem

Merchants are leaving money on the table. They bundle products randomly without data. Customers don’t see relevant add-ons because there’s no algorithm. A merchant with $10k/month revenue could boost AOV by 10-20% with smart bundling, but needs ML to identify what actually sells together.

What it does

• Analyze all historical orders to build a co-purchase matrix: product X was bought with product Y in N orders
• Rank product pairs by frequency (% of X orders that also contain Y) and by AOV lift (average order value increase when both are purchased)
• Calculate confidence scores (pairs with high frequency and high AOV lift score highest)
• Handle seasonal trends: reduce weight of seasonal products in off-season (winter boots don’t pair well in July)
• For each product, generate a list of 2-5 top recommended products to bundle with it
• Display recommendation widget on product detail page: ‘Frequently bought with this’ showing 3-5 recommended products with images, price, and ‘Add to Cart’ button
• A/B test different recommendation sets (variant A uses one algorithm, variant B uses a different ranking or product set)
• Track recommendation metrics: click-through rate (customer clicks ‘Add to Cart’), conversion rate (customer completes purchase), AOV of orders containing a recommendation
• Provide analytics dashboard: co-purchase matrix heatmap, top 10 recommended pairs, A/B test results with statistical significance
• Webhook events: product_recommendation_displayed, product_recommendation_clicked, product_recommendation_purchased

What it deliberately does NOT do

Each boundary carries its reason. A boundary without a reason gets crossed by the next person who reads this.

• Does not handle variable/mixed bundles where customers customize contents — that’s a separate bundle builder feature.
• Does not enforce bundle purchase (e.g., require buying both items together) — recommendations are suggestions, not requirements.
• Does not create discount codes automatically — core pricing module handles discounts; this module just surfaces recommendations.
• Does not segment recommendations by customer type/RFM/history — that’s paid CRM module; this module is based on global co-purchase data only.
• Does not handle inventory constraints (e.g., ‘don’t recommend out-of-stock items’) — that’s storefront logic, core owns.
• Does not provide full cross-selling (recommend any related product) — focused on ‘bought together’ pattern only, not broader category affinity.

Data model

New tables: ProductPair (productIdA, productIdB, frequency, aovLift, confidence, lastUpdated); RecommendationTest (id, shopId, productId, variantA, variantB, startDate, endDate, createdAt); RecommendationImpression (id, shopId, productId, recommendedProductId, variantAssignment, impressionTimestamp); RecommendationClick (id, impressionId, clickTimestamp); RecommendationConversion (id, shopId, recommendationTestId, secondOrderId, aovIncrease). Requires indexing on Orders table for historical co-purchase analysis during rebuild. Migration required on first upgrade: backfill ProductPair table by analyzing existing orders.

API

• GET /products/{id}/recommendations — returns recommended products for a product (public)
• GET /admin/recommendations/analysis — returns co-purchase matrix and top pairs (staff only)
• POST /admin/recommendations/tests — create A/B test
• GET /admin/recommendations/tests/{id} — view test results
• DELETE /admin/recommendations/tests/{id} — cancel running test
• POST /admin/recommendations/rebuild — trigger full co-purchase re-analysis

Every route added here must also appear in src/pages/openapi.json.ts — a test fails the build if it does not.

Admin

Recommendations dashboard showing: (1) co-purchase heatmap matrix (products on X and Y axes, cell color intensity = frequency/AOV lift); (2) top 10 recommended pairs with frequency and AOV lift; (3) toggle ‘Enable recommendations on product pages’ (on/off globally); (4) control ‘Number of recommendations to show’ (2-5); (5) A/B test builder with variant creator and results viewer; (6) analytics card: ‘Click-through rate’, ‘Conversion rate’, ‘AOV lift’ for last 30 days; (7) test results page showing statistical significance (if applicable); (8) ‘Rebuild recommendations’ button (background job, may take minutes on large order history).

The seam — why this is paid

Core provides: order data (line items, totals, timestamps), product catalog, product detail page rendering, ‘Add to Cart’ button functionality, click/purchase event tracking. Paid module provides: co-purchase algorithm, frequency/AOV calculation, confidence scoring, seasonal adjustments, A/B test logic, recommendation ranking, analytics aggregation. The recommendation widget is rendered by core (as a slot in the product detail template), but the recommended product list is generated by the paid module.

Paid module owns ML product pairing algorithm and A/B test infrastructure; core provides bundle interface only

Dependencies

• Orders table with line items (existing)
• Products table (existing)
• Product detail page template (core)
• Click/purchase event tracking (core event system)
• Background job system (for rebuild-recommendations job)

Acceptance checks

Each of these must be able to fail. Before claiming this is done, break the code deliberately and watch each one go red.

• Co-purchase matrix correctly identifies 2+ products bought together in the same order (line items with the same order ID)
• Top recommendation for product A is a product that was purchased together with A in >5% of A’s orders
• Product ‘winter boot’ does not appear in summer month recommendations (seasonal adjustment working)
• A/B test shows click rate and conversion rate for each variant, broken out separately
• Recommendation widget on product detail page displays up to 5 recommended products with image, price, and ‘Add to Cart’ button
• Clicking ‘Add to Cart’ on a recommended product increments the click counter for that recommendation
• Completing a purchase that includes a recommended product increments the conversion counter
• Two A/B tests cannot run on the same product simultaneously (blocked with error message)

Risks

If co-purchase analysis is slow, recommendations are stale and not refreshed (merchants disable feature). If algorithm is biased toward best sellers (not pairs), all products recommend the same top 5 (marketing decay). If A/B test sample size is too small (<100 per variant), winner is random noise (wrong business decision). If ‘Add to Cart’ for recommendations fails silently, widget appears broken and CTR crashes. If seasonal adjustment is hardcoded to wrong hemisphere/region, winter items show in summer (poor UX).

Commercial context

The anchor is what the nearest equivalent charges on Shopify or Magento today. It is context for a pricing decision, not the decision.

---

Generated from the commerce plan. See docs/COMMERCE-PLAN.md for the full catalogue and ../../AI-GUIDE.md for how to work on this repository.