The CLV API provides on-demand and batch computation of Customer Lifetime Value scores based on RFM (Recency, Frequency, Monetary) analysis of interaction summaries.
See the CLV feature page for business context, scoring methodology, and segment definitions. Base Path
GET /api/v1/customers//clv
Returns the cached CLV record for a customer. If no cached record exists, computes CLV on-demand and caches the result.
Roles: Any authenticated user (no role check — only requires valid tenant).
Path Parameters
| Parameter | Type | Description |
|---|
customerId | string | Customer identifier |
Response 200
Response Fields
| Field | Type | Description |
|---|
clvScore | integer | Composite CLV score (0-100) |
predictedRevenue | number | Projected revenue over 24-month lifespan |
churnProbability | number | Probability of churn (0.0-1.0) based on recency |
rfmRecency | integer | Days since last interaction |
rfmFrequency | integer | Total number of interactions (impressions) |
rfmMonetary | number | Total conversion value |
segment | string | Customer segment: high, medium, low, or at_risk |
computedAt | string | ISO 8601 timestamp of when the CLV was computed |
source | string | cached if returned from storage, computed if calculated on-demand |
Example
POST /api/v1/customers//clv
Force recompute CLV for a specific customer. Always recalculates from current interaction summaries, ignoring any cached value.
Roles: Any authenticated user (no role check — only requires valid tenant).
Path Parameters
| Parameter | Type | Description |
|---|
customerId | string | Customer identifier |
Response 200
Example
POST /api/v1/clv/compute
Batch compute CLV for all customers in the tenant, or filtered to a specific segment. Processes customers in batches of 50 with parallel execution.
Roles: Any authenticated user (no role check — only requires valid tenant).
Request Body
| Field | Type | Required | Description |
|---|
segment | string | No | Filter to recompute only customers in this segment. One of: high, medium, low, at_risk. Omit to recompute all. |
When a segment filter is provided, the batch includes customers currently in that segment plus any new customers without a CLV record. This ensures new customers are always scored.
Response 200
Response Fields
| Field | Type | Description |
|---|
success | boolean | Whether the batch completed |
computed | integer | Number of customers successfully computed |
errors | integer | Number of customers that failed computation |
segment | string | The segment filter used, or all |
Example
Error Codes
| Status | Code | Description |
|---|
400 | Bad Request | Invalid segment value. Must be high, medium, low, or at_risk |
401 | Unauthorized | Missing or invalid authentication |
403 | Forbidden | Insufficient role for this operation |
500 | Server Error | Internal error during CLV computation |
Using CLV in ranking
A customer’s clvScore can directly tilt the PRIE formula
at decision time. Set a non-zero clvWeight on a formula Score node (or the
clv weight key on a Ranking Profile) and the
engine multiplies each candidate’s score by impact^(clvWeight × clvScore/100) —
high-CLV customers see high-impact offers ranked higher. A customer with no CLV
row is left untouched (the term is skipped). See
Scoring strategies for the worked mechanics.
See Also
