Lifetime Value Dashboard

Paid pluginsize Mplanned, not built

Indicative price, not an offer: €34/mo; LTV calculation, payback period, segment drill-down

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

A paid analytics module calculating customer Lifetime Value (LTV) and payback period (when CAC is recovered), with segment drill-down and retention prediction. Core provides order data; this pack adds LTV calculation engine, payback forecasting, and dashboard UI.

The problem

Merchant pays €20 CAC per customer but doesn’t know if that customer will ever spend €40 (2x ROI). Without LTV visibility, they overspend on ads, underestimate unit economics, and miss that high-LTV segments are worth higher CAC.

What it does

• LTV calculation: total spent by customer over all time, or forecast LTV (avg spend per month × retention rate × N months)
• Payback period: months until cumulative purchases ≥ CAC (e.g., CAC €20 paid back in 3 months if €7/mo)
• Segment LTV: LTV by product category, region, acquisition channel, customer tier (if defined)
• Payback forecast: if payback is 3 months and customer is 2 months old, estimated payback date is today + 1 month
• Dashboard cards: overall LTV, payback period, LTV by segment (segment picker), trend (LTV rising/falling?)
• Drill-down: click segment, see customer list (order by LTV desc), each customer’s purchase history and payback status

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.

• CAC input/tracking—owned by marketing/analytics module; this assumes CAC is provided via API or manual input
• Customer acquisition cost by channel (organic vs paid)—owned by attribution module
• Predicting which customers will churn—owned by churn prediction module
• Customer lifetime value for subscriptions—owned by subscriptions module (different calculation)
• Margin-adjusted LTV (LTV minus COGS)—owned by profitability module

Data model

New entities: CustomerLTV (id, customerId, ltv, ltv_forecast, payback_period_months, payback_date, cac, segment_tags[], calculatedAt); LTVSegment (id, merchantId, name, criteria[channel|category|region|tier], avg_ltv, customer_count). Links: CustomerLTV.customerId → Customer. Migration: none (new data).

API

• POST /api/v1/customers/{customerId}/ltv — calculate LTV for one customer (staff only)
• GET /api/v1/customers/{customerId}/ltv — fetch LTV data (staff only)
• POST /api/v1/ltv/run-analysis — calculate LTV for all customers (async job) (staff only)
• GET /api/v1/ltv/segments — list LTV by segment (channel, category, region) (staff only)
• GET /api/v1/ltv/dashboard — dashboard summary (overall LTV, payback period, trend, segments) (staff only)
• GET /api/v1/customers/by-ltv — list customers sorted by LTV (staff only, paginated, filterable)

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

Admin

LTV Dashboard page: KPI cards showing overall LTV (e.g., €87), overall payback period (e.g., 2.5 months), trend icon (up/down). Segment dropdown: select segment (all, by channel, by category, by region). Segment card: shows segment LTV, customer count, comparison to overall LTV. Drill-down table: top 20 customers in segment, LTV, payback date, last purchase date, sortable.

The seam — why this is paid

Core owns: order history (revenue, dates, customer ID), customer records. Paid pack owns: LTV calculation engine (formula, forecast logic), payback period logic, segment grouping. Seam drawn here because LTV models vary (simple sum vs. forecast vs. margin-adjusted)—support team chooses formula for each merchant.

Support commitment: LTV model accuracy, payback forecasting, retention prediction

Dependencies

• core:orders — read order dates, revenue, customer ID
• core:customers — read customer data (acquisition date for payback calculation)
• core:scheduler — calculate LTV periodically (daily/weekly)
• assumption: CAC is provided externally or stored in merchant settings

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 customer with purchase history [€50 Jan, €30 Mar, €20 May] has LTV = €100
• A customer with CAC €20 who has spent €40 in 2 months has payback_period = 2 months
• LTV forecast for a customer with avg €10/month and 50% monthly retention for 6 months = €10 × (1 + 0.5 + 0.25 + 0.125 + 0.0625 + 0.03) = ~€18.84
• Segment ‘Paid Ads Channel’ shows avg LTV €75 for 200 customers, vs overall avg €60 for 1000 customers
• Drill-down for ‘Organic’ segment shows 15 customers sorted by LTV desc; customer A (€250 LTV, payback in 2 mo) appears above customer B (€50 LTV, payback in 5 mo)
• LTV calculation runs nightly without blocking customer queries; results are available by morning
• Two merchants see different LTV data (multitenancy enforced)
• A customer with 0 purchases has LTV = €0 and no payback date (not an error, just absent)

Risks

LTV forecast assumes constant retention—reality is declining. Document the assumption. CAC must be set per customer or per cohort—if missing, payback_date is null (handle gracefully). LTV calculation at scale (100K+ customers) takes time—schedule during off-peak or cache hourly. If a customer refunds (returns product), should that reduce LTV? Decide on policy and document. Very new customers (0 months old) have LTV = purchases so far, forecast is unreliable—flag with confidence interval or show historical only.

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.