> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kaireonai.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Customer Lifetime Value (CLV)
> RFM-based CLV scoring that segments customers, predicts revenue, and estimates churn probability.
**See also**: [Clv REST API reference](/api-reference/clv) for request/response shapes, status codes, and error semantics.
Customer Lifetime Value (CLV) quantifies how much a customer is worth to your business over their entire relationship. KaireonAI computes CLV using an **RFM model** (Recency, Frequency, Monetary) derived from interaction summaries, then uses the score to segment customers and predict future revenue.
CLV scores feed directly into the decisioning engine. A high-value customer at risk of churning can automatically receive retention offers, while a new customer with growing engagement can be fast-tracked into loyalty programs.
CLV is computed automatically on first access and cached. Batch recomputation can be triggered via the API or scheduled as a cron job.
***
## Business Value
| Use Case | How CLV Helps |
| ------------------------ | ---------------------------------------------------------------------------------- |
| **Retention targeting** | Identify `at_risk` customers before they churn and route them into retention flows |
| **Budget allocation** | Invest more in high-CLV segments, optimize spend on low-CLV segments |
| **Offer prioritization** | Use CLV as an input to the PRIE ranking formula's value dimension |
| **Executive reporting** | Track CLV distribution across your customer base over time |
***
## How It Works
### RFM Model
CLV is derived from three behavioral dimensions:
| Dimension | What It Measures | Weight |
| ------------- | --------------------------------------------- | ------ |
| **Recency** | Days since last interaction (lower is better) | 35% |
| **Frequency** | Total number of interactions (impressions) | 35% |
| **Monetary** | Total conversion value in currency | 30% |
Each dimension is normalized against **tenant-wide percentiles** so scores are relative to your customer base, not absolute values.
### CLV Score Calculation
```
CLV Score = (RecencyNorm x 0.35 + FrequencyNorm x 0.35 + MonetaryNorm x 0.30) x 100
```
The score ranges from **0 to 100**, where 100 represents the highest-value customer in your tenant.
### Segment Assignment
| Segment | Criteria |
| --------- | ------------------------------------------------------ |
| `high` | CLV score >= 75th percentile |
| `medium` | CLV score >= 25th percentile |
| `low` | CLV score \< 25th percentile |
| `at_risk` | 30+ days since last contact AND has prior interactions |
The `at_risk` segment takes priority over score-based segments. A customer with a high CLV score who has gone inactive for 30+ days will be flagged as `at_risk` rather than `high`.
### Churn Probability
Churn probability uses a sigmoid curve based on recency:
* **0 days inactive**: \~7% churn probability
* **30 days inactive**: 50% churn probability
* **90+ days inactive**: approaches 100%
### Predicted Revenue
Predicted revenue extrapolates from the customer's monthly average spend over a 24-month projected lifespan:
```
Predicted Revenue = (Total Monetary Value / Months Active) x 24
```
***
## Configuration
CLV computation requires no configuration. It automatically uses interaction summaries that the platform collects through the [Respond API](/api-reference/respond).
To tune the model, you can adjust weights and thresholds through the platform settings:
| Setting | Default | Description |
| ------------------- | --------- | ------------------------------------------ |
| Recency weight | 0.35 | Weight of recency dimension in CLV score |
| Frequency weight | 0.35 | Weight of frequency dimension |
| Monetary weight | 0.30 | Weight of monetary dimension |
| At-risk threshold | 30 days | Days of inactivity before flagging at-risk |
| Lifespan projection | 24 months | Months used for revenue projection |
***
## Using CLV
### Single Customer Lookup
```bash theme={null}
curl https://playground.kaireonai.com/api/v1/customers/CUST-001/clv \
-H "X-Tenant-Id: my-tenant"
```
Returns the cached CLV or computes on-demand if no cached record exists.
### Force Recompute
```bash theme={null}
curl -X POST https://playground.kaireonai.com/api/v1/customers/CUST-001/clv \
-H "X-Tenant-Id: my-tenant"
```
### Batch Compute
Recompute CLV for all customers (or a specific segment):
```bash theme={null}
curl -X POST https://playground.kaireonai.com/api/v1/clv/compute \
-H "X-Tenant-Id: my-tenant" \
-H "Content-Type: application/json" \
-d '{ "segment": "at_risk" }'
```
### Example Response
```json theme={null}
{
"customerId": "CUST-001",
"clvScore": 72,
"predictedRevenue": 1440.00,
"churnProbability": 0.119,
"rfmRecency": 5,
"rfmFrequency": 48,
"rfmMonetary": 360.00,
"segment": "high",
"computedAt": "2026-04-03T10:30:00.000Z",
"source": "cached"
}
```
***
## CLV in Decision Flows
CLV scores are available as customer context in Decision Flows. You can use them in:
* **Decisioning gates** with `propensity_threshold` type to restrict offers to high-value customers
* **Computed fields** using `customer.clv_score` in formulas
* **Ranking profiles** where CLV feeds the value dimension of the PRIE score
***
## API Reference
See the full [CLV API Reference](/api-reference/clv) for all endpoints, request/response schemas, and error codes.
***
## Next Steps
Full endpoint documentation with examples.
Define custom metrics that feed into CLV and decisioning.
Use CLV scores to personalize the decision pipeline.
View CLV alongside all other customer data in one call.