Cohort Analysis

Paid pluginsize Mplanned, not built

Indicative price, not an offer: €39/mo; retention curves, cohort drill-down, export

Generated from docs/plan/paid/cohort-analysis/PLAN.md in the AstroBaaS repository. Nothing described below is implemented — it is the written plan for it.

A paid analytics module to analyze customer cohorts (customers acquired in a month/channel), calculate retention/repeat purchase rates, and forecast revenue from cohort trends. Core provides order history; this pack adds cohort grouping logic, retention curve calculation, and trend visualization.

The problem

Merchant knows 100 customers bought in January, but which stayed? Are January customers worth €100 LTV or €50? Without cohort retention curves, merchant cannot forecast revenue or know if marketing spend on January is profitable.

What it does

• Cohort grouping: segment customers by acquisition month, channel (organic/paid/affiliate), or custom attribute
• Retention calculation: X% of January cohort bought again in Feb, Y% in Mar, etc. (retention curve)
• Repeat purchase rate: % of cohort that made >1 purchase, average purchases per cohort member
• Revenue per cohort: total revenue by cohort, avg revenue per customer (ARR/cohort)
• Cohort visualization: heatmap (rows=cohorts, cols=months) showing retention %, or line chart showing retention decay
• Forecasting: if Jan cohort has 40% 3-month retention, estimate revenue from Feb/Mar cohorts
• Drill-down: click cohort, see customer list, their purchase history, repeat purchase timing

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.

• Churn prediction (which customers will leave)—owned by predictive analytics, not this module
• Customer segmentation (behavioral clusters)—owned by segmentation module
• Attribution modeling (customer acquired via channel X)—owned by attribution module; this assumes attribution is set
• Custom cohort definitions (e.g., ‘high-value then churned’)—too flexible; use drill-down for manual inspection
• Subscription-specific metrics (MRR, ARR churn)—owned by subscriptions module

Data model

New entities: Cohort (id, merchantId, name, groupBy[month|channel|attribute], startDate, endDate, cohortSize); CohortMetric (id, cohortId, cohortAge[months], retentionRate, repeatPurchaseRate, revenueTotal, avgRevenuePerCustomer, calculatedAt). Links: Cohort.merchantId → Shop. No new customer entity fields needed (acquisition date, channel already in Customer). Migration: none if Customer already has acquisition_date and acquisition_channel; otherwise backfill from order history.

API

• POST /api/v1/cohorts — define a cohort (group by month/channel, date range) (staff only)
• GET /api/v1/cohorts/{id} — fetch cohort + retention curve data (staff only)
• GET /api/v1/cohorts/{id}/retention — retention data for visualization (staff only)
• GET /api/v1/cohorts/{id}/customers — list customers in cohort, their purchase history (staff only, paginated)
• POST /api/v1/cohorts/run-analysis — calculate retention/repeat-purchase for all cohorts (staff only, async job)
• GET /api/v1/cohorts/forecast — forecast revenue based on historical retention curves (staff only)

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

Admin

Cohorts page: list all cohorts (name, size, created date). Cohort detail: show retention heatmap (rows=cohort month, cols=months since acquisition, cells=retention %), line chart of retention decay. Drill-down section: customers in this cohort, sortable by purchase count/LTV. Forecast card: ‘If Feb cohort follows Jan trend (40% 3-month retention), projected revenue from Feb cohort in April is €X’.

The seam — why this is paid

Core owns: order history (line items, dates, customer ID), customer records (acquisition date, channel). Paid pack owns: Cohort entity, retention curve calculation, forecast logic. Seam drawn here because cohort calculations are computationally intensive and require ongoing refinement—support team monitors accuracy and adjusts for edge cases.

Support commitment: cohort calculation accuracy, retention forecasting

Dependencies

• core:orders — read order dates, customer IDs, revenue amounts
• core:customers — read customer acquisition date and channel
• core:scheduler — calculate cohort metrics periodically (daily/weekly)
• assumption: Customer.acquisitionDate and Customer.acquisitionChannel are set

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.

• A cohort is defined: ‘Customers acquired Jan 2026 via Organic’. Query returns cohort size (50 customers), creation date 2026-01-01
• Retention curve is calculated: 50 Jan customers, 20 (40%) purchased again in Feb, 15 (30%) in Mar, 10 (20%) in Apr. Heatmap shows 40%, 30%, 20% in correct cells
• A cohort drill-down shows list of 50 customers, each with purchase count and total LTV; customer A: 3 purchases, €300 LTV; customer B: 1 purchase, €50 LTV
• Forecast for Feb cohort: ‘Feb had 60 customers. If retention follows Jan trend (40% at 1 month), expect 24 repeat purchases in Mar’
• Cohort analysis runs daily; retention metrics are updated without blocking queries (async job completes, then metrics available)
• Two merchants see only their own cohort data (multitenancy enforced)
• A cohort with 0 repeat purchases still appears in the list and shows 0% retention (not hidden)
• Clicking a cohort size number (50) shows the full customer list, sortable by date joined, purchase count, LTV

Risks

Retention calculation must handle customers who refunded—decide whether to count them or exclude. If cohort analysis runs too frequently, it monopolizes DB—schedule during off-peak or cache results. Acquisition date must be accurate; if missing or wrong, cohort membership is wrong. Forecast assumes future retention = past retention; caveat must be shown to user. Very large cohorts (100K+) may take >5 min to calculate; must return partial results or timeout gracefully.

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.