Retention and Expansion | Bootspring Docs

The Retention and Expansion workflow helps you keep users engaged and grow revenue from your existing customer base. From predicting churn to driving upsells, this guide provides actionable strategies for maximizing customer lifetime value.

Overview#

Property	Value
Components	4 (Churn Prevention, Health Scoring, Retention Tactics, Expansion)
Tier	Free
Typical Duration	Ongoing optimization
Best For	SaaS products with recurring revenue

Outcomes#

A successful retention program delivers:

Reduced churn rate
Increased Net Revenue Retention (NRR)
Predictive churn model
Automated intervention workflows
Expansion revenue playbook

Why Retention Matters#

THE RETENTION IMPACT

5% improvement in retention = 25-95% increase in profits

Customer Acquisition Cost vs Retention Cost
┌─────────────────────────────────────────┐
│ Acquiring new customer: $100           │
│ Retaining existing:     $20            │
│ Ratio:                  5:1            │
└─────────────────────────────────────────┘

Revenue Math:
┌─────────────────────────────────────────┐
│ 1000 customers × $100/mo = $100K MRR    │
│                                         │
│ 5% monthly churn = $5K lost             │
│ 3% monthly churn = $3K lost             │
│ Difference: $24K/year saved             │
└─────────────────────────────────────────┘

Component 1: Churn Prediction#

Churn Signals#

Identify users at risk of churning:

// lib/churn/signals.ts
interface ChurnSignal {
  signal: string;
  weight: number;
  threshold: number;
  lookbackDays: number;
}

const churnSignals: ChurnSignal[] = [
  {
    signal: 'login_frequency_drop',
    weight: 0.25,
    threshold: 0.5, // 50% reduction
    lookbackDays: 14,
  },
  {
    signal: 'feature_usage_decline',
    weight: 0.20,
    threshold: 0.4,
    lookbackDays: 30,
  },
  {
    signal: 'support_tickets_spike',
    weight: 0.15,
    threshold: 3, // 3+ tickets
    lookbackDays: 7,
  },
  {
    signal: 'no_new_projects',
    weight: 0.15,
    threshold: 30, // days
    lookbackDays: 30,
  },
  {
    signal: 'team_size_decrease',
    weight: 0.10,
    threshold: 1, // any reduction
    lookbackDays: 30,
  },
  {
    signal: 'billing_failure',
    weight: 0.15,
    threshold: 1,
    lookbackDays: 7,
  },
];

Churn Risk Score#

// lib/churn/score.ts
export async function calculateChurnRisk(userId: string): Promise<{
  score: number;
  signals: string[];
  recommendation: string;
}> {
  const user = await prisma.user.findUnique({
    where: { id: userId },
    include: { subscription: true, events: true },
  });

  let riskScore = 0;
  const triggeredSignals: string[] = [];

  // Check each signal
  for (const signal of churnSignals) {
    const isTriggered = await checkSignal(user, signal);
    if (isTriggered) {
      riskScore += signal.weight;
      triggeredSignals.push(signal.signal);
    }
  }

  // Normalize to 0-100
  const normalizedScore = Math.min(Math.round(riskScore * 100), 100);

  return {
    score: normalizedScore,
    signals: triggeredSignals,
    recommendation: getRecommendation(normalizedScore, triggeredSignals),
  };
}

function getRecommendation(score: number, signals: string[]): string {
  if (score >= 70) {
    return 'High risk - immediate outreach required';
  } else if (score >= 40) {
    return 'Medium risk - schedule check-in';
  } else {
    return 'Low risk - continue monitoring';
  }
}

Churn Prediction SQL#

-- Identify at-risk users
WITH user_activity AS (
  SELECT
    user_id,
    COUNT(CASE
      WHEN created_at > NOW() - INTERVAL '7 days' THEN 1
    END) as events_last_7,
    COUNT(CASE
      WHEN created_at BETWEEN NOW() - INTERVAL '14 days'
           AND NOW() - INTERVAL '7 days' THEN 1
    END) as events_prev_7,
    MAX(created_at) as last_active
  FROM events
  GROUP BY user_id
),
churn_risk AS (
  SELECT
    u.id,
    u.email,
    u.company_name,
    s.plan,
    s.mrr,
    ua.events_last_7,
    ua.events_prev_7,
    ua.last_active,
    CASE
      WHEN ua.events_last_7 = 0 THEN 80
      WHEN ua.events_last_7 < ua.events_prev_7 * 0.5 THEN 60
      WHEN ua.events_last_7 < ua.events_prev_7 * 0.75 THEN 40
      ELSE 20
    END as risk_score
  FROM users u
  JOIN subscriptions s ON u.id = s.user_id
  LEFT JOIN user_activity ua ON u.id = ua.user_id
  WHERE s.status = 'active'
)
SELECT *
FROM churn_risk
WHERE risk_score >= 40
ORDER BY risk_score DESC, mrr DESC;

Component 2: Health Scoring#

Customer Health Score#

// lib/health/score.ts
interface HealthMetrics {
  productAdoption: number;   // Feature usage breadth
  engagement: number;        // Frequency and depth
  growth: number;            // Team/usage expansion
  sentiment: number;         // NPS, support interactions
  relationship: number;      // Executive engagement, renewals
}

export async function calculateHealthScore(accountId: string): Promise<{
  score: number;
  metrics: HealthMetrics;
  status: 'healthy' | 'at_risk' | 'critical';
}> {
  const metrics: HealthMetrics = {
    productAdoption: await calculateAdoptionScore(accountId),
    engagement: await calculateEngagementScore(accountId),
    growth: await calculateGrowthScore(accountId),
    sentiment: await calculateSentimentScore(accountId),
    relationship: await calculateRelationshipScore(accountId),
  };

  // Weighted average
  const weights = {
    productAdoption: 0.30,
    engagement: 0.25,
    growth: 0.15,
    sentiment: 0.15,
    relationship: 0.15,
  };

  const score = Object.entries(metrics).reduce(
    (sum, [key, value]) => sum + value * weights[key as keyof HealthMetrics],
    0
  );

  return {
    score: Math.round(score),
    metrics,
    status: score >= 70 ? 'healthy' : score >= 40 ? 'at_risk' : 'critical',
  };
}

Health Score Components#

Component	Weight	Metrics
Product Adoption	30%	Features used, depth of usage
Engagement	25%	DAU, session length, frequency
Growth	15%	Seat expansion, usage growth
Sentiment	15%	NPS score, support satisfaction
Relationship	15%	Renewals, executive engagement

Health Dashboard#

// components/HealthDashboard.tsx
export function HealthDashboard({ accounts }: { accounts: Account[] }) {
  const healthyCount = accounts.filter(a => a.healthStatus === 'healthy').length;
  const atRiskCount = accounts.filter(a => a.healthStatus === 'at_risk').length;
  const criticalCount = accounts.filter(a => a.healthStatus === 'critical').length;

  return (
    <div className="grid grid-cols-3 gap-4">
      <MetricCard
        title="Healthy"
        value={healthyCount}
        color="green"
        percentage={Math.round(healthyCount / accounts.length * 100)}
      />
      <MetricCard
        title="At Risk"
        value={atRiskCount}
        color="yellow"
        percentage={Math.round(atRiskCount / accounts.length * 100)}
      />
      <MetricCard
        title="Critical"
        value={criticalCount}
        color="red"
        percentage={Math.round(criticalCount / accounts.length * 100)}
      />
    </div>
  );
}

Component 3: Retention Tactics#

Automated Interventions#

// lib/retention/automations.ts
interface RetentionAutomation {
  trigger: string;
  condition: (user: User) => boolean;
  action: (user: User) => Promise<void>;
  priority: 'high' | 'medium' | 'low';
}

const automations: RetentionAutomation[] = [
  {
    trigger: 'no_login_7_days',
    condition: (user) => daysSinceLastLogin(user) >= 7,
    action: async (user) => {
      await sendEmail(user.email, 'we_miss_you', {
        name: user.name,
        lastFeature: user.lastFeatureUsed,
      });
    },
    priority: 'medium',
  },
  {
    trigger: 'billing_failure',
    condition: (user) => user.subscription.status === 'past_due',
    action: async (user) => {
      await sendEmail(user.email, 'update_payment', {
        name: user.name,
        updateUrl: generatePaymentUpdateLink(user),
      });
      await createTask('CS', `Follow up on billing: ${user.email}`);
    },
    priority: 'high',
  },
  {
    trigger: 'low_adoption',
    condition: (user) => user.featuresUsed < 3 && user.daysActive > 14,
    action: async (user) => {
      await sendEmail(user.email, 'feature_discovery', {
        name: user.name,
        suggestedFeatures: getUnusedFeatures(user),
      });
    },
    priority: 'medium',
  },
];

// Run automations daily
export async function runRetentionAutomations() {
  const users = await prisma.user.findMany({
    where: { subscription: { status: 'active' } },
    include: { subscription: true, events: true },
  });

  for (const user of users) {
    for (const automation of automations) {
      if (automation.condition(user)) {
        await automation.action(user);
        await logAutomation(user.id, automation.trigger);
      }
    }
  }
}

Re-engagement Email Sequences#

Day	Email	Purpose
7	"We miss you"	Gentle reminder with value prop
14	Feature highlight	Show underused features
21	Success story	Social proof from similar users
28	Special offer	Discount or extended trial

Cancellation Flow#

// components/CancellationFlow.tsx
'use client';

import { useState } from 'react';

export function CancellationFlow({ subscription }: { subscription: Subscription }) {
  const [step, setStep] = useState(1);
  const [reason, setReason] = useState('');
  const [feedback, setFeedback] = useState('');

  const reasons = [
    { value: 'too_expensive', label: 'Too expensive', offer: 'discount' },
    { value: 'missing_features', label: 'Missing features I need', offer: 'roadmap' },
    { value: 'not_using', label: 'Not using it enough', offer: 'pause' },
    { value: 'competitor', label: 'Switching to competitor', offer: 'comparison' },
    { value: 'business_closed', label: 'Business closed', offer: null },
    { value: 'other', label: 'Other', offer: 'support' },
  ];

  async function handleCancel() {
    await fetch('/api/subscriptions/cancel', {
      method: 'POST',
      body: JSON.stringify({ reason, feedback }),
    });
    // Redirect to confirmation
  }

  // Step 1: Ask why
  if (step === 1) {
    return (
      <div className="max-w-md mx-auto p-6">
        <h2 className="text-xl font-bold mb-4">We're sorry to see you go</h2>
        <p className="text-muted-foreground mb-6">
          Before you cancel, please tell us why:
        </p>
        <div className="space-y-3">
          {reasons.map((r) => (
            <label
              key={r.value}
              className={`flex items-center p-3 rounded border cursor-pointer ${
                reason === r.value ? 'border-primary' : 'border-border'
              }`}
            >
              <input
                type="radio"
                name="reason"
                value={r.value}
                checked={reason === r.value}
                onChange={(e) => setReason(e.target.value)}
                className="mr-3"
              />
              {r.label}
            </label>
          ))}
        </div>
        <button
          onClick={() => setStep(2)}
          disabled={!reason}
          className="mt-6 w-full py-2 bg-primary text-primary-foreground rounded"
        >
          Continue
        </button>
      </div>
    );
  }

  // Step 2: Make an offer based on reason
  const selectedReason = reasons.find(r => r.value === reason);

  if (step === 2 && selectedReason?.offer) {
    return <RetentionOffer type={selectedReason.offer} onDecline={() => setStep(3)} />;
  }

  // Step 3: Final confirmation
  return (
    <div className="max-w-md mx-auto p-6">
      <h2 className="text-xl font-bold mb-4">Final step</h2>
      <p className="text-muted-foreground mb-4">
        Any feedback to help us improve?
      </p>
      <textarea
        value={feedback}
        onChange={(e) => setFeedback(e.target.value)}
        placeholder="Optional feedback..."
        className="w-full p-3 border rounded min-h-[100px]"
      />
      <button
        onClick={handleCancel}
        className="mt-6 w-full py-2 bg-destructive text-destructive-foreground rounded"
      >
        Cancel Subscription
      </button>
    </div>
  );
}

Retention Offers#

Reason	Offer
Too expensive	20% discount for 3 months
Not using enough	Pause subscription (up to 3 months)
Missing features	Roadmap preview + feedback call
Competitor	Comparison guide + success call

Component 4: Expansion Revenue#

Expansion Playbook#

EXPANSION OPPORTUNITIES

Upsell (More of same)
├── Higher tier plan
├── More seats/users
└── Higher usage limits

Cross-sell (Different products)
├── Add-on features
├── Integrations
└── Professional services

Net Revenue Retention Target: 110%+

Upsell Triggers#

// lib/expansion/triggers.ts
interface UpsellTrigger {
  condition: string;
  check: (account: Account) => boolean;
  offer: string;
  priority: number;
}

const upsellTriggers: UpsellTrigger[] = [
  {
    condition: 'approaching_seat_limit',
    check: (a) => a.seatsUsed >= a.seatsAllowed * 0.8,
    offer: 'Upgrade to add more team members',
    priority: 1,
  },
  {
    condition: 'hitting_usage_limit',
    check: (a) => a.apiCalls >= a.apiLimit * 0.9,
    offer: 'Upgrade for unlimited API calls',
    priority: 1,
  },
  {
    condition: 'using_all_features',
    check: (a) => a.featuresUsed >= a.featuresAvailable * 0.8,
    offer: 'Unlock advanced features with Pro',
    priority: 2,
  },
  {
    condition: 'high_engagement',
    check: (a) => a.dau / a.totalUsers > 0.6 && a.plan === 'starter',
    offer: 'Your team loves us - upgrade for more!',
    priority: 3,
  },
];

Expansion Email Sequence#

// Triggered when upsell opportunity detected
const expansionEmails = [
  {
    day: 0,
    subject: "You're getting close to your limit",
    template: 'limit_approaching',
    cta: 'View upgrade options',
  },
  {
    day: 3,
    subject: 'Unlock more with our Pro plan',
    template: 'feature_comparison',
    cta: 'Compare plans',
  },
  {
    day: 7,
    subject: 'Special offer for growing teams',
    template: 'limited_discount',
    cta: 'Get 20% off upgrade',
  },
];

Net Revenue Retention Calculation#

-- Calculate NRR
WITH cohort_revenue AS (
  SELECT
    DATE_TRUNC('month', first_payment_date) as cohort_month,
    SUM(CASE
      WHEN payment_month = cohort_month THEN mrr
      ELSE 0
    END) as starting_mrr,
    SUM(CASE
      WHEN payment_month = cohort_month + INTERVAL '12 months' THEN mrr
      ELSE 0
    END) as ending_mrr
  FROM (
    SELECT
      customer_id,
      DATE_TRUNC('month', created_at) as payment_month,
      MIN(DATE_TRUNC('month', created_at)) OVER (PARTITION BY customer_id) as first_payment_date,
      SUM(amount) as mrr
    FROM payments
    GROUP BY customer_id, DATE_TRUNC('month', created_at)
  ) payments_by_month
  GROUP BY DATE_TRUNC('month', first_payment_date)
)
SELECT
  cohort_month,
  starting_mrr,
  ending_mrr,
  ROUND(ending_mrr / NULLIF(starting_mrr, 0) * 100, 1) as nrr_percent
FROM cohort_revenue
WHERE cohort_month < NOW() - INTERVAL '12 months'
ORDER BY cohort_month;

Recommended Agents#

Phase	Agent	Purpose
Analytics	analytics-expert	Churn analysis, health scoring
Development	backend-expert	Automation implementation
Copy	copywriting-expert	Retention emails
Strategy	strategy-expert	Expansion playbook

Metrics Dashboard#

Metric	Definition	Target
Monthly Churn	% customers lost	< 3%
Net Revenue Retention	Revenue from existing	> 110%
Gross Churn	Revenue lost	< 5%
Expansion Rate	Revenue gained from existing	> 5%
Health Score	Avg customer health	> 70

Deliverables#

Deliverable	Description
Churn model	Predictive scoring system
Health dashboard	Customer health tracking
Automation playbook	Trigger-based interventions
Cancellation flow	Optimized offboarding
Expansion playbook	Upsell/cross-sell strategies

Best Practices#

Act early - Intervene at first sign of disengagement
Personalize - Generic outreach doesn't work
Make it easy to stay - Reduce friction in retention offers
Listen to churned users - Exit interviews are gold
Celebrate success - Recognize and reward engaged users
Measure everything - Track what actually prevents churn

Common Pitfalls#

Ignoring early signals - Don't wait until they cancel
Annoying interventions - Quality over quantity
One-size-fits-all - Segment your approach
Ignoring feedback - If many churn for same reason, fix it
Aggressive upselling - Bad timing destroys trust

Product-Market Fit - Strong PMF = better retention
Metrics Dashboard - Track retention KPIs
Acquisition Channels - Acquire the right users
Post-Launch - Early retention optimization