> ## 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.

# CLV API

> Compute, retrieve, and batch-process Customer Lifetime Value scores using RFM analysis.

<Note>
  **See also**: [Clv concept and configuration](/studio/clv) for what this API powers, when to call it, and how it is configured.
</Note>

The CLV API provides on-demand and batch computation of Customer Lifetime Value scores based on RFM (Recency, Frequency, Monetary) analysis of interaction summaries.

<Info>
  See the [CLV feature page](/studio/clv) for business context, scoring methodology, and segment definitions.
</Info>

## Base Path

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

***

## GET /api/v1/customers/{customerId}/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`

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

### 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

```bash theme={null}
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/{customerId}/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`

```json theme={null}
{
  "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

```bash theme={null}
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. |

<Note>
  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.
</Note>

### Response `200`

```json theme={null}
{
  "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

```bash theme={null}
# 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](/decisioning/prie-formula-design)
at decision time. Set a non-zero `clvWeight` on a `formula` Score node (or the
`clv` weight key on a [Ranking Profile](/api-reference/ranking-profiles)) 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](/decisioning/scoring-strategies) for the worked mechanics.

## See Also

* [CLV Feature Guide](/studio/clv)
* [Scoring Strategies](/decisioning/scoring-strategies)
* [Unified Profile](/api-reference/unified-profile)
* [Behavioral Metrics](/api-reference/behavioral-metrics)