CLV API

See also: Clv concept and configuration for what this API powers, when to call it, and how it is configured.

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

/api/v1/customers/{customerId}/clv    # Single customer
/api/v1/clv/compute                    # Batch compute

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`

{
  "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"
}

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

curl https://playground.kaireonai.com/api/v1/customers/CUST-001/clv \
  -H "X-Tenant-Id: my-tenant" \
  -H "Authorization: Bearer <token>"

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`

{
  "customerId": "CUST-001",
  "clvScore": 74,
  "predictedRevenue": 1520.00,
  "churnProbability": 0.119,
  "rfmRecency": 5,
  "rfmFrequency": 50,
  "rfmMonetary": 380.00,
  "segment": "high",
  "computedAt": "2026-04-03T11:00:00.000Z",
  "source": "recomputed"
}

Example

curl -X POST https://playground.kaireonai.com/api/v1/customers/CUST-001/clv \
  -H "X-Tenant-Id: my-tenant" \
  -H "Authorization: Bearer <token>"

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`

{
  "success": true,
  "computed": 342,
  "errors": 0,
  "segment": "all"
}

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

# Recompute all customers
curl -X POST https://playground.kaireonai.com/api/v1/clv/compute \
  -H "X-Tenant-Id: my-tenant" \
  -H "Content-Type: application/json"

# Recompute only at-risk customers
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" }'

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.

Overview

Decisioning

Studio

Data

Algorithms & Models

Content & Metrics

Orchestration

Customers & Traces

Events & Attribution

Analytics

AI

Testing & Simulation

Export & Import

Admin

Integrations

Base Path

GET /api/v1/customers//clv

Path Parameters

Response `200`

Response Fields

Example

POST /api/v1/customers//clv

Path Parameters

Response `200`

Example

POST /api/v1/clv/compute

Request Body

Response `200`

Response Fields

Example

Error Codes

Using CLV in ranking

See Also

​Base Path

​GET /api/v1/customers//clv

​Path Parameters

​Response 200

​Response Fields

​Example

​POST /api/v1/customers//clv

​Path Parameters

​Response 200

​Example

​POST /api/v1/clv/compute

​Request Body

​Response 200

​Response Fields

​Example

​Error Codes

​Using CLV in ranking

​See Also

Base Path

GET /api/v1/customers//clv

Path Parameters

Response `200`

Response Fields

Example

POST /api/v1/customers//clv

Path Parameters

Response `200`

Example

POST /api/v1/clv/compute

Request Body

Response `200`

Response Fields

Example

Error Codes

Using CLV in ranking

See Also