Predictive Thresholds

Configure site-level threshold bands for churn risk, purchase propensity, and CLV segmentation.

Audience: Lifecycle and CRM teams using predictive segments for targeting decisions.

Critical: Predictive thresholds are managed under site endpoints (/api/v1/sites/:id/predictive-thresholds*), not AI site endpoints.

Segments Module AI Personalization Cohorts

Who This Page Is For

Use this page when you need to define score cutoffs for predictive segmenting and regularly recalculate user predictive scores.

Quick Start (2-5 Minutes)

Read current thresholds

Fetch current score thresholds for site.

GET /api/v1/sites/:id/predictive-thresholds

Update thresholds

Set high/medium cutoffs for churnRisk, purchasePropensity, and CLV.

PUT /api/v1/sites/:id/predictive-thresholds

Get distribution stats

Inspect how users distribute across threshold bands.

GET /api/v1/sites/:id/predictive-thresholds/stats

Recalculate predictive scores

Trigger score recalculation after threshold or model updates.

POST /api/v1/sites/:id/predictive-thresholds/calculate

Apply segments

Use predictive segment rules after score recalculation.

Use segments module with predictive type audiences.

Predictive threshold endpoints

GET  /api/v1/sites/:id/predictive-thresholds
PUT  /api/v1/sites/:id/predictive-thresholds
GET  /api/v1/sites/:id/predictive-thresholds/stats
POST /api/v1/sites/:id/predictive-thresholds/calculate

Required Fields / Minimum Payload

Field	Required	Type	Used by events	Description
`churnRisk.high / churnRisk.medium`	Optional	`number (0..100)`	Update thresholds	Must satisfy high > medium.
`purchasePropensity.high / purchasePropensity.medium`	Optional	`number (0..100)`	Update thresholds	Must satisfy high > medium.
`clv.high / clv.medium`	Optional	`number`	Update thresholds	Must satisfy high > medium.
`autoAdjust`	Optional	`boolean`	Update thresholds	Controls automatic adjustment behavior where supported.

Threshold update example

{
"churnRisk": { "high": 70, "medium": 40 },
"purchasePropensity": { "high": 65, "medium": 35 },
"clv": { "high": 500, "medium": 200 },
"autoAdjust": false
}

Event or Endpoint Decision Matrix

Scenario	Use This	Why
Need baseline threshold config	GET /sites/:id/predictive-thresholds	Read current segmentation cutoffs.
Need threshold policy update	PUT /sites/:id/predictive-thresholds	Primary write path with validation rules.
Need audience distribution visibility	GET /sites/:id/predictive-thresholds/stats	Shows impact of threshold settings.
Need recomputation after changes	POST /sites/:id/predictive-thresholds/calculate	Applies threshold/model updates to user scores.
Need targeting rollout	Segments module predictive audiences	Operational usage of computed score bands.

Common Errors and Fixes

Threshold update fails validation

Cause: high value not greater than medium value.

Fix: Set high > medium for each metric block.

Stats endpoint unchanged after update

Cause: Scores not recalculated yet.

Fix: Run calculate endpoint after threshold changes.

Predictive segment reach unexpectedly low

Cause: Thresholds too strict for current data distribution.

Fix: Review stats and adjust thresholds incrementally.

Confusion with AI personalization endpoints

Cause: Predictive thresholds mistaken for /ai/sites/* resources.

Fix: Use /sites/:id/predictive-thresholds* endpoints only.

Production Checklist

Threshold definitions are documented with business rationale.Required
Validation rule high > medium is enforced for all threshold pairs.Required
Score recalculation is part of threshold change runbook.Required
Stats are reviewed after each threshold update.Required
Predictive segment effects are monitored in campaign outcomes.Required