Churn Prediction & Upsell Detection

Introduced in v1.0.76

SaaS Factory now ships with a fully autonomous churn prediction and upsell detection engine. The system continuously scores every customer for churn risk and surfaces expansion opportunities — with no human involvement required.

---

How It Works

Churn Risk Scoring

The core of the system is computeChurnScore(), a weighted heuristic model that evaluates each customer across six dimensions and produces a single composite risk score alongside a detailed signals array.

compositeScore = Σ(dimensionScore × weight)

The Six Dimensions

1. Customer Status (0 – 0.9) Reflects the customer's current lifecycle state — active, flagged at-risk, payment lapsed, or churned. This is the highest-impact single dimension.

2. Payment Failure History (0 – 0.25) Accumulates weight based on the number and recency of failed payment events. Even a single recent failure shifts the score meaningfully.

3. Inactivity (0 – 0.35) Measures the elapsed time since the customer last engaged with the product. Prolonged inactivity is one of the strongest churn predictors in the model.

4. Usage Trend (0 – 0.2) Tracks the directional change in feature usage or session activity over a rolling window. A declining trend adds risk weight; a growing trend subtracts it.

5. Subscription Lifecycle (-0.15 – +0.15) Accounts for where the customer sits within their subscription arc. Newer customers carry slightly more risk; long-tenured customers receive a small score reduction.

6. Renewal Proximity (variable) Weights the score based on how close the customer is to their next renewal date. Risk peaks in the window immediately before renewal.

Signals Array

Every score output includes a signals array — one entry per triggered condition — with explicit impact and weight values. This makes every score fully explainable and auditable.

{
  "customerId": "cus_abc123",
  "score": 0.61,
  "signals": [
    { "dimension": "inactivity", "impact": 0.35, "weight": 0.35 },
    { "dimension": "paymentFailure", "impact": 0.15, "weight": 0.25 },
    { "dimension": "usageTrend", "impact": 0.10, "weight": 0.20 }
  ]
}

---

Upsell Opportunity Detection

detectUpsellOpportunities() runs independently of the churn model and identifies customers who are strong candidates for an upgrade or expansion.

Two trigger types are evaluated:

• High Growth — Customers whose usage has expanded rapidly, signalling they may be approaching plan limits or would benefit from a higher tier.
• Tenure — Long-standing customers who have demonstrated sustained engagement and loyalty, making them receptive to expansion conversations.

When a trigger fires, a row is inserted into the upsellOpportunities table. From there, automated campaign logic can take over.

---

Data Model

The engine is backed by three dedicated tables:

churnRiskScores

Stores the latest computed score for each customer, along with the full signals array and a timestamp. Scores can be refreshed on-demand or on a scheduled cadence.

upsellOpportunities

Records each detected upsell opportunity with its trigger type, customer reference, and current status (open, actioned, closed).

winBackCampaigns

Tracks automated win-back campaigns targeting churned or high-risk customers, including conversion outcomes.

---

API Reference

All churn and upsell functionality is exposed via the churn router.

Score Management

Procedure	Description
churn.listScores	Paginated list of all customer churn scores
churn.getScore	Current score and signals for one customer
churn.refreshScore	Force a score recalculation for one customer
churn.getSummary	Aggregate risk distribution across all customers

Upsell Management

Procedure	Description
churn.listUpsells	List all detected upsell opportunities
churn.updateUpsellStatus	Advance or close an opportunity
churn.detectForCustomer	Run upsell detection for a specific customer

Win-Back Campaigns

Procedure	Description
churn.listCampaigns	List all win-back campaigns
churn.markConverted	Record a successful conversion
churn.setCampaignStatus	Update campaign status (active, paused, complete)

---

Autonomy Model

The churn and upsell engine runs without human input:

1. Scores are computed continuously as customer behavior data changes.
2. Upsell opportunities are detected and logged automatically when thresholds are crossed.
3. Win-back campaigns are initiated and tracked to conversion — all within the platform.

No manual intervention is needed to identify at-risk customers or expansion opportunities. The system handles discovery, prioritization, and tracking end-to-end.