Customer Health Scoring Guide

Overview

Customer health scoring is a critical metric for proactive account management and churn prevention. The health score quantifies customer engagement, satisfaction, and likelihood to continue the relationship. This guide explains how health scores are calculated, monitored, and used to drive customer success initiatives.

Understanding Health Scores

What is a Health Score?

A customer health score is a numerical value (0-100) that represents the overall health of the customer relationship based on multiple factors including:

• Purchase frequency and recency
• Product usage and engagement
• Support interactions and satisfaction
• Payment history and reliability
• Communication responsiveness
• Contract renewal likelihood

Health Score Ranges

Score Range	Health Status	Color Code	Action Required
90-100	Excellent	Green	Upsell/expansion opportunity
75-89	Good	Light Green	Regular monitoring, quarterly reviews
60-74	Fair	Yellow	Proactive check-ins, monthly reviews
40-59	At Risk	Orange	Immediate attention, weekly monitoring
0-39	Critical	Red	Emergency intervention, daily monitoring

Health Score Components

Engagement Score (30 points)

• Product login frequency
• Feature adoption rate
• Time spent in platform
• Active user count (for business customers)

Financial Health (25 points)

• On-time payment history
• Credit utilization
• Average order value trends
• Purchase frequency

Support Health (20 points)

• Support ticket volume
• Resolution time satisfaction
• Escalation frequency
• Customer satisfaction (CSAT) scores

Relationship Health (15 points)

• Response rate to communications
• Meeting attendance
• Stakeholder engagement
• Feedback participation

Product Value (10 points)

• ROI achievement
• Goal attainment
• Success milestone completion
• Testimonial/referral willingness

Retrieving Health Scores

Get Customer Health Score

Endpoint: GET /api/v1/crm/customers/{id}/health-score

Authentication: Required (Bearer token)

Response (200 OK):

{
  "data": {
    "customer_id": 568,
    "overall_health_score": 82,
    "health_status": "good",
    "trend": "stable",
    "last_calculated_at": "2025-12-17T18:00:00Z",
    "score_breakdown": {
      "engagement_score": 27,
      "engagement_max": 30,
      "engagement_percentage": 90,
      "financial_health": 21,
      "financial_max": 25,
      "financial_percentage": 84,
      "support_health": 16,
      "support_max": 20,
      "support_percentage": 80,
      "relationship_health": 11,
      "relationship_max": 15,
      "relationship_percentage": 73,
      "product_value": 7,
      "product_value_max": 10,
      "product_value_percentage": 70
    },
    "key_metrics": {
      "days_since_last_purchase": 7,
      "days_since_last_login": 1,
      "lifetime_value": 250000.00,
      "average_order_value": 25000.00,
      "support_tickets_open": 0,
      "support_tickets_closed_30d": 2,
      "average_resolution_time_hours": 4.5,
      "csat_score": 4.7,
      "payment_history_score": 100,
      "active_users_percentage": 85,
      "feature_adoption_percentage": 78
    },
    "risk_factors": [
      {
        "factor": "declining_engagement",
        "severity": "low",
        "description": "Login frequency decreased by 15% over last 30 days",
        "recommendation": "Schedule check-in to understand usage patterns"
      }
    ],
    "opportunities": [
      {
        "type": "expansion",
        "description": "Customer using 78% of features, good candidate for advanced tier",
        "estimated_value": 15000.00
      }
    ],
    "next_review_date": "2026-01-15T00:00:00Z"
  }
}

Get At-Risk Customers

Endpoint: GET /api/v1/crm/customers/at-risk

Authentication: Required (Bearer token)

Query Parameters:

• segment (string) - Filter by customer segment
• per_page (integer) - Results per page (default: 50)
• sort (string) - Sort field (default: last_order_date)
• direction (string) - Sort direction (asc, desc)
• includes (string) - Relationships to include

Example Request:

GET /api/v1/crm/customers/at-risk?segment=vip&per_page=25&sort=health_score&direction=asc

Response (200 OK):

{
  "data": [
    {
      "id": 569,
      "customer_number": "CUST-000569",
      "company_name": "TechStart Inc",
      "email": "contact@techstart.com",
      "status": "active",
      "segment": "vip",
      "health_score": 45,
      "health_status": "at_risk",
      "lifetime_value": 150000.00,
      "days_since_last_order": 45,
      "days_since_last_activity": 20,
      "risk_factors": [
        {
          "factor": "no_recent_purchases",
          "severity": "high",
          "days": 45
        },
        {
          "factor": "declining_engagement",
          "severity": "medium",
          "percentage_drop": 40
        },
        {
          "factor": "increased_support_tickets",
          "severity": "medium",
          "ticket_count": 8
        }
      ],
      "account_manager": {
        "id": 7,
        "name": "Jane Manager",
        "email": "jane@yourcompany.com"
      },
      "last_activity_at": "2025-11-27T10:00:00Z",
      "created_at": "2024-06-15T10:00:00Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 25,
    "total": 12,
    "last_page": 1
  },
  "summary": {
    "total_at_risk_customers": 12,
    "total_at_risk_value": 1250000.00,
    "average_health_score": 48.5,
    "critical_count": 3,
    "needs_immediate_attention": 9
  }
}

Updating Health Scores

Manual Health Score Update

Endpoint: PATCH /api/v1/crm/customers/{id}/health-score

Authentication: Required (Bearer token)

Request Body:

{
  "score": 65,
  "notes": "Adjusted health score after successful customer check-in. Addressed concerns about feature complexity. Customer committed to increased usage over next 30 days."
}

Validation Rules:

• score (integer, required) - Health score value (0-100)
• notes (string, optional) - Reason for manual adjustment

Response (200 OK):

{
  "message": "Health score updated successfully",
  "data": {
    "id": 569,
    "customer_number": "CUST-000569",
    "health_score": 65,
    "health_status": "fair",
    "previous_score": 45,
    "score_change": 20,
    "updated_at": "2025-12-17T19:00:00Z",
    "updated_by": {
      "id": 7,
      "name": "Jane Manager"
    },
    "notes": "Adjusted health score after successful customer check-in. Addressed concerns about feature complexity. Customer committed to increased usage over next 30 days."
  }
}

When to Manually Update

Manual updates are appropriate when:

• Automated scoring doesn't capture recent positive interactions
• Customer commits to specific improvement actions
• Major account issues have been resolved
• Strategic relationship changes occur
• Qualitative factors aren't reflected in metrics

Health Score Calculation

Automatic Calculation

Health scores are automatically recalculated:

• Real-time triggers: After significant events (purchase, support ticket closure, payment)
• Scheduled: Daily batch processing for all customers
• On-demand: When viewing customer details or generating reports

Calculation Formula

Overall Health Score =
  (Engagement Score × 0.30) +
  (Financial Health × 0.25) +
  (Support Health × 0.20) +
  (Relationship Health × 0.15) +
  (Product Value × 0.10)

Component Scoring Details

1. Engagement Score (0-30 points)

Points = (
  (Login Frequency Score × 0.25) +
  (Feature Adoption Rate × 0.25) +
  (Active Users Percentage × 0.25) +
  (Time in Platform × 0.25)
) × 30

Calculation Factors:

• Login frequency: Daily (30 pts), Weekly (20 pts), Monthly (10 pts), Rare (5 pts)
• Feature adoption: 80%+ (30 pts), 60-79% (20 pts), 40-59% (15 pts), <40% (10 pts)
• Active users: For business accounts, percentage of purchased seats actively used
• Time in platform: Average daily/weekly usage time

2. Financial Health (0-25 points)

Points = (
  (Payment History × 0.40) +
  (Purchase Recency × 0.30) +
  (Purchase Growth Trend × 0.30)
) × 25

Calculation Factors:

• Payment history: On-time payments, no outstanding invoices
• Purchase recency: Days since last purchase (0-30 days = full points, degrade after)
• Purchase growth: Increasing, flat, or declining purchase patterns

3. Support Health (0-20 points)

Points = (
  (Ticket Volume × 0.30) +
  (Resolution Satisfaction × 0.40) +
  (Escalation Rate × 0.30)
) × 20

Calculation Factors:

• Ticket volume: Fewer tickets = healthier (adjusted for customer size)
• Resolution satisfaction: CSAT scores from ticket closures
• Escalation rate: Percentage of tickets requiring escalation

4. Relationship Health (0-15 points)

Points = (
  (Communication Response Rate × 0.40) +
  (Meeting Attendance × 0.30) +
  (Stakeholder Engagement × 0.30)
) × 15

Calculation Factors:

• Response rate: Percentage of emails/calls returned within SLA
• Meeting attendance: QBR and check-in attendance rate
• Stakeholder engagement: Number of engaged contacts vs. total contacts

5. Product Value (0-10 points)

Points = (
  (Goal Achievement × 0.40) +
  (ROI Realization × 0.30) +
  (Reference Willingness × 0.30)
) × 10

Calculation Factors:

• Goal achievement: Percentage of stated goals accomplished
• ROI realization: Customer-reported ROI vs. expected
• Reference willingness: Participation in case studies, referrals, reviews

Health Score Trends

Trend Analysis

Health scores are tracked over time to identify trends:

Trend	Description	Indicator
Improving	Score increased ≥5 points in 30 days	↗️ Green
Stable	Score changed <5 points in 30 days	→ Blue
Declining	Score decreased ≥5 points in 30 days	↘️ Yellow
Critical Decline	Score decreased ≥15 points in 30 days	⬇️ Red

Trend Indicators in Response:

{
  "trend": "declining",
  "trend_direction": "down",
  "score_change_30d": -12,
  "score_change_90d": -18,
  "trend_severity": "high"
}

Churn Risk Assessment

Risk Factor Detection

The system automatically identifies risk factors that contribute to churn probability:

High-Risk Factors (Critical):

• No purchase in 60+ days (for typical purchase cycle)
• Health score below 40
• Multiple unresolved escalated tickets
• Payment 30+ days overdue
• Key stakeholder departed
• Competitor engagement detected

Medium-Risk Factors (Warning):

• Login frequency decreased >30%
• Feature adoption declined
• Support ticket volume increased >50%
• Missed 2+ scheduled meetings
• No response to communications in 14+ days

Low-Risk Factors (Monitor):

• Minor engagement fluctuations
• Seasonal purchasing patterns
• Single missed meeting
• Temporary contact unavailability

Churn Probability Calculation

Churn Probability = f(Health Score, Risk Factors, Customer Tenure, Segment)

Where:
- Health Score 0-39: 70-90% churn probability
- Health Score 40-59: 40-60% churn probability
- Health Score 60-74: 15-30% churn probability
- Health Score 75-100: 0-10% churn probability

Adjusted by:
+ Number and severity of risk factors
+ Customer tenure (newer customers = higher risk)
+ Segment (enterprise = lower risk than SMB)

Business Scenarios

Scenario 1: Identifying At-Risk VIP Customer

Context: VIP customer's health score drops from 85 to 52 over 60 days

Workflow:

1. System alerts account manager of declining health
2. Review health score breakdown to identify issues
3. Schedule urgent customer check-in
4. Create action plan to address issues
5. Monitor health score weekly

API Calls:

# 1. Get detailed health score
GET /api/v1/crm/customers/569/health-score

# Response shows:
# - Engagement down 40% (login frequency dropped)
# - Support tickets increased 3x
# - Feature adoption stagnant at 45%
# - Payment still on-time (positive)

# 2. Get customer activities to understand context
GET /api/v1/crm/customers/569/activities?from_date=2025-10-01

# 3. Update customer status
PATCH /api/v1/crm/customers/569
{
  "status": "at_risk",
  "tags": ["at-risk", "vip-churn-prevention", "high-priority"],
  "notes": "Health score dropped to 52. Key issues: decreased usage, increased support tickets. Scheduling urgent call to understand root causes."
}

# 4. Create urgent activity
POST /api/v1/crm/activities
{
  "type": "call",
  "subject": "URGENT: VIP Customer Health Check - Churn Risk",
  "customer_id": 569,
  "priority": "high",
  "scheduled_at": "2025-12-18T09:00:00Z",
  "assigned_user_id": 7,
  "notes": "Address declining engagement and support issues. Understand if technical problems or change in business needs."
}

# 5. After successful call, update health score
PATCH /api/v1/crm/customers/569/health-score
{
  "score": 68,
  "notes": "Post-intervention: Identified technical issues with API integration. Engineering engaged to resolve. Customer committed to ramping up usage once resolved. Upgraded score based on commitment and issue identification."
}

Scenario 2: Proactive Expansion with Healthy Customer

Context: Customer maintains 88 health score, high engagement, expansion opportunity identified

Workflow:

1. Identify healthy, high-potential customers
2. Review feature adoption and usage patterns
3. Identify expansion opportunities
4. Create upsell opportunity
5. Schedule strategic planning session

API Calls:

# 1. Get customers with excellent health scores
GET /api/v1/crm/customers?health_score_min=85&segment=standard&sort_by=lifetime_value&sort_direction=desc

# 2. Get detailed health score for target customer
GET /api/v1/crm/customers/570/health-score

# Response shows:
# - Health score: 88
# - Feature adoption: 92%
# - High engagement: daily logins
# - Using 78% of advanced features
# - Opportunity: Not using enterprise tier features that they need

# 3. Create expansion opportunity
POST /api/v1/crm/opportunities
{
  "name": "Customer 570 - Enterprise Tier Upgrade",
  "customer_id": 570,
  "value": 50000.00,
  "stage": "qualification",
  "expected_close_date": "2026-02-28",
  "probability": 75,
  "description": "Customer showing high engagement with current tier. Using 92% of features. Excellent candidate for enterprise tier with additional users and features.",
  "tags": ["expansion", "tier-upgrade", "health-score-88"]
}

# 4. Schedule strategic planning meeting
POST /api/v1/crm/activities
{
  "type": "meeting",
  "subject": "Strategic Planning: Growth & Expansion Discussion",
  "customer_id": 570,
  "opportunity_id": 890,
  "scheduled_at": "2025-12-20T14:00:00Z",
  "assigned_user_id": 7,
  "notes": "Discuss enterprise tier features, ROI analysis, and expansion timeline."
}

Scenario 3: Preventing Churn Through Early Detection

Context: Health score trend shows consistent decline over 90 days (78 → 65 → 58)

Workflow:

1. System detects declining trend
2. Analyze health score components to identify root cause
3. Proactive outreach before critical threshold
4. Implement corrective actions
5. Monitor recovery

API Calls:

# 1. Get at-risk customers with declining trends
GET /api/v1/crm/customers/at-risk?sort=health_score&direction=asc

# 2. Get detailed health analysis
GET /api/v1/crm/customers/571/health-score

# Response shows:
# - Current score: 58 (Fair, but declining)
# - Trend: Down 20 points in 90 days
# - Primary issue: Support health dropped (16 tickets in 60 days vs. 3 typically)
# - Secondary issue: Relationship health down (not responding to emails)

# 3. Review support tickets to understand issues
GET /api/v1/support/tickets?customer_id=571&status=open

# 4. Create customer success intervention plan
POST /api/v1/crm/activities
{
  "type": "meeting",
  "subject": "Customer Success Review - Address Recent Challenges",
  "customer_id": 571,
  "priority": "high",
  "scheduled_at": "2025-12-19T10:00:00Z",
  "assigned_user_id": 7,
  "notes": "Proactive outreach. Customer experiencing technical issues (16 tickets in 60 days). Not responding to routine emails. Need to understand if they're overwhelmed or considering alternatives."
}

# 5. Assign customer success specialist
PATCH /api/v1/crm/customers/571
{
  "tags": ["needs-attention", "support-heavy", "declining-health"],
  "custom_fields": {
    "customer_success_specialist": "Sarah Johnson",
    "success_plan_start_date": "2025-12-19",
    "success_plan_duration": "90 days"
  },
  "notes": "Assigned customer success specialist. 90-day success plan to resolve technical issues and improve satisfaction."
}

# 6. After intervention, track recovery
# Weekly health score checks:
GET /api/v1/crm/customers/571/health-score

# Goal: Return to 70+ within 60 days

Scenario 4: Quarterly Health Review for VIP Segment

Context: Quarterly business review season, analyze all VIP customer health

Workflow:

1. Generate VIP customer health report
2. Segment VIPs by health status
3. Prioritize review meetings
4. Create action plans for at-risk VIPs
5. Identify expansion opportunities with healthy VIPs

API Calls:

# 1. Get all VIP customers with health scores
GET /api/v1/crm/customers?segment=vip&per_page=100&includes=health_score,account_manager

# 2. Get specifically at-risk VIPs
GET /api/v1/crm/customers/at-risk?segment=vip

# 3. For each VIP, get detailed health data
GET /api/v1/crm/customers/{id}/health-score

# 4. Schedule QBR meetings based on health status
# For healthy VIPs (75+): Growth-focused QBR
POST /api/v1/crm/activities
{
  "type": "meeting",
  "subject": "Q1 2026 - Quarterly Business Review",
  "customer_id": 572,
  "scheduled_at": "2026-01-15T14:00:00Z",
  "description": "Agenda: Review Q4 results, discuss expansion opportunities, strategic planning for 2026"
}

# For at-risk VIPs (60-): Issue-resolution focused
POST /api/v1/crm/activities
{
  "type": "meeting",
  "subject": "Priority QBR - Success Planning Session",
  "customer_id": 573,
  "priority": "high",
  "scheduled_at": "2025-12-20T10:00:00Z",
  "description": "Agenda: Address declining health score, resolve outstanding issues, develop 90-day success plan"
}

Best Practices

1. Monitor Health Scores Regularly

Frequency by Segment:

• VIP/Enterprise: Daily monitoring, weekly reviews
• Standard: Weekly monitoring, monthly reviews
• SMB: Bi-weekly monitoring, quarterly reviews

Use Automation:

• Set up alerts for scores dropping below 60
• Create automatic tasks when scores decline >15 points in 30 days
• Generate weekly at-risk customer reports

2. Act on Declining Trends Early

Response Timeline:

• Score drops below 60: Contact within 24 hours
• Score drops below 45: Contact same day, escalate to management
• Score drops below 30: Emergency intervention, executive involvement

Don't Wait:

• Proactive outreach at 65 prevents escalation to 45
• Early intervention has 3x higher success rate
• Waiting until critical often means relationship already lost

3. Combine Quantitative and Qualitative Data

Quantitative (Automated):

• Usage metrics
• Purchase patterns
• Support tickets
• Payment history

Qualitative (Manual):

• Customer sentiment in calls
• Stakeholder relationships
• Strategic alignment
• Competitive threats

Best Results: Automated scoring + human judgment

4. Validate Score Accuracy

Regular Calibration:

• Review churned customers' final health scores
• Analyze false positives (low score, didn't churn)
• Analyze false negatives (high score, did churn)
• Adjust weighting and thresholds quarterly

Feedback Loop:

• Account managers report score accuracy
• Incorporate feedback into algorithm
• Document manual overrides and reasons

5. Take Action on Insights

Health Score is Not Enough:

• Requires action plan
• Needs resources allocated
• Must be tied to outcomes

Action Requirements:

• Clear ownership (account manager assigned)
• Defined intervention steps
• Timeline for follow-up
• Success metrics defined

6. Celebrate Health Improvements

Recognize Success:

• Track health score improvements
• Celebrate customers moving from at-risk to healthy
• Share success stories across team
• Reward account managers for turnarounds

Build Process:

• Document what worked
• Replicate successful interventions
• Create playbooks for common scenarios

Health Score Reporting

Key Metrics to Track

Portfolio Health:

• Average health score across all customers
• Distribution by health status (% in each range)
• Trend: Improving vs. declining customers
• At-risk customer count and value

Segment Analysis:

• Health score by customer segment
• VIP health (should be >80 average)
• Enterprise health trends
• SMB churn prediction accuracy

Intervention Effectiveness:

• Success rate of interventions
• Average time to recover health score
• ROI of customer success efforts
• Prevented churn value

Predictive Accuracy:

• Churn prediction accuracy rate
• False positive rate
• False negative rate
• Early warning effectiveness

Integration Points

With Support Module

• Support ticket volume and resolution affect health score
• Health score visible in support dashboard
• Priority routing for low-health customers
• Automatic escalation triggers

With Sales Module

• Health score influences upsell/cross-sell timing
• Expansion opportunities identified for healthy customers
• Renewal risk flagged for at-risk customers
• Account value at risk calculated

With Finance Module

• Payment behavior affects financial health component
• At-risk customers flagged for collections
• Credit limit adjustments based on health
• Churn prediction impacts revenue forecasting

With Product Module

• Usage metrics feed engagement score
• Feature adoption tracked and scored
• Product feedback linked to health trends
• Beta program eligibility based on health

Troubleshooting

Health Score Not Updating

Issue: Health score remains static despite customer activity

Possible Causes:

• Automated calculation job not running
• Data not being collected from source systems
• Cache not invalidating

Solution:

# Force health score recalculation
PATCH /api/v1/crm/customers/{id}/health-score
{
  "score": 75,
  "notes": "Manual recalculation after verifying data is correct"
}

Health Score Seems Inaccurate

Issue: Customer has high health score but churned (or vice versa)

Analysis Steps:

1. Review component breakdown
2. Check data quality for each component
3. Validate metric definitions
4. Compare with qualitative assessment

Calibration:

• Adjust component weights
• Refine metric definitions
• Incorporate additional signals
• Document edge cases

At-Risk List Overwhelming

Issue: Too many at-risk customers to effectively manage

Solutions:

1. Prioritize by Value: Focus on high-LTV customers first
2. Segment by Cause: Group by common issues (support, engagement, etc.)
3. Automate Responses: Create automated workflows for common scenarios
4. Increase Resources: Add customer success team members
5. Improve Onboarding: Prevent customers from becoming at-risk

Related Documentation

• Customer Management Guide - Managing customer accounts
• Lead Management - Lead scoring comparison
• Opportunity Pipeline - Expansion opportunities
• Activity Management - Customer interaction tracking