Guide / health scoring
How to build a customer health score people can explain
A useful health score is not one mysterious number. It is a compact representation of observable risk signals that the team can inspect and act on.
Definition
What is a customer health score?
A customer health score is a repeatable measure of an account's likelihood of remaining successful or becoming at risk, calculated from signals such as product usage, engagement recency, billing status, support activity and renewal timing.
Four-signal model
Use signals an operator can verify.
Each component should describe observable account behavior or commercial state, not an unexplained model output.
| Usage trend | Compare recent product activity with the preceding period. A large decline can be more informative than an absolute usage count. |
|---|---|
| Recency | Measure how long it has been since meaningful activity. Define meaningful activity for the product rather than counting any event. |
| Payment state | Failed or delinquent payments are direct commercial risk signals and should not be hidden inside a generic engagement metric. |
| Renewal proximity | The same warning matters more when a material renewal is near. Combine risk with revenue and timing to order the work queue. |
Explainability
The score should answer “why now?”
When a CSM asks why an account turned red, the system should point to concrete causes instead of asking the team to trust a black box.
Inspect OpenRetention's scoring logic.
View score.js
The current implementation is visible in the repository and can be changed by the operator.