# Predictive LTV & Churn — Full documentation

> Complete guide to the Predictive LTV & Churn plugin for WooCommerce: installation, Email Service Provider configuration, dashboard usage, understanding the predictive model and automatic RFM segmentation. Overview Predictive LTV &…

- Page: <https://www.datafirefly.com/en/documentation/dfpredictivectvchurn/>
- Language: en
- Last updated: 2026-07-01
- Other languages: [fr](https://www.datafirefly.com/documentation/dfpredictivectvchurn/index.md), [es](https://www.datafirefly.com/es/documentation/dfpredictivectvchurn/index.md), [de](https://www.datafirefly.com/de/documentation/dfpredictivectvchurn/index.md), [it](https://www.datafirefly.com/it/documentation/dfpredictivectvchurn/index.md), [pl](https://www.datafirefly.com/pl/documentation/dfpredictivectvchurn/index.md), [nl](https://www.datafirefly.com/nl/documentation/dfpredictivectvchurn/index.md), [pt](https://www.datafirefly.com/pt/documentation/dfpredictivectvchurn/index.md)
- Index: <https://www.datafirefly.com/en/documentation/llms.txt>

Complete guide to the Predictive LTV & Churn plugin for WooCommerce: installation, Email Service Provider configuration, dashboard usage, understanding the predictive model and automatic RFM segmentation.

## Overview

**Predictive LTV & Churn** is a WooCommerce plugin that scores every customer in your store along two dimensions: their predicted Lifetime Value and their churn probability. Based on this, it automatically classifies each customer into one of 9 actionable business segments, then syncs those insights to Brevo, Mailchimp or Klaviyo so you can run finely targeted email campaigns.

The engine takes inspiration from the BG/NBD model used by data scientists, but it works with zero configuration: it continuously learns your store's actual baseline (repeat rate, average basket, interval between orders) to give reasonable predictions from the very first order.

**Typical use case.** A customer places their first order. The plugin detects it, immediately computes their predicted LTV (low confidence but useful value), assigns them to the "New customer" segment, and pushes them to Brevo with the attributes DFPLC_PREDICTED_LTV and DFPLC_SEGMENT. Your Brevo automation can then trigger a tailored welcome sequence.

## Installation

### Requirements

- WordPress 6.2 or higher
- WooCommerce 7.0 or higher (tested up to 9.4)
- PHP 7.4 or higher (8.x recommended)
- An API key for at least one ESP among Brevo, Mailchimp or Klaviyo

### Installation steps

1. Download the `dfpredictivectvchurn.zip` file from your DataFirefly account.
2. In the WordPress admin, go to **Plugins > Add New > Upload Plugin**.
3. Select the ZIP and click **Install Now**.
4. Click **Activate Plugin**.
5. On activation, the plugin automatically creates 3 dedicated tables in your database: `wp_dfplc_customer_scores`, `wp_dfplc_export_queue`, `wp_dfplc_baseline`.

The plugin formally declares its compatibility with WooCommerce High Performance Order Storage (HPOS) via `FeaturesUtil`. No direct access to `wp_postmeta` tables, everything goes through `wc_get_orders()`.

## First run and initial scoring

Right after activation, your dashboard is empty: no customer has been scored yet. You have two options.

### Option 1: automatic incremental scoring

Do nothing. The plugin will score customers as new orders come in. This is the gentlest path for large bases.

### Option 2: retroactive scoring of the full history

Go to **Predictive LTV > Dashboard** and click the **Recalculate all customers** button. The plugin will iterate through your order history in batches of 50 customers, compute each score, update the store baseline, then refresh the RFM quintiles. Depending on your base size, expect:

- Fewer than 500 customers: a few seconds
- 500 to 5,000 customers: 30 seconds to 3 minutes
- More than 5,000 customers: 5 to 15 minutes (processing continues in the background)

On a store with more than 20,000 customers, it is recommended to temporarily disable the "real-time recalculation" option during initial scoring to avoid double load.

## Email Service Provider configuration

The plugin supports three ESPs simultaneously. You can enable one, two or all three. Each configuration lives in **Predictive LTV > Settings**.

### Brevo (formerly Sendinblue)

1. Log into your Brevo account, go to **SMTP & API > API Keys**.
2. Create a v3 key with at least the _Contacts_ permissions.
3. Create a dedicated list (for example "DataFirefly LTV"), note its numeric ID.
4. In the plugin, paste the API key into **Brevo API Key** and the list ID into **Brevo List ID**.
5. Click **Test connection** to validate the credentials.

The following attributes will be created automatically on each Brevo contact: `DFPLC_PREDICTED_LTV`, `DFPLC_LTV_CONF`, `DFPLC_CHURN_PROB`, `DFPLC_SEGMENT`, `DFPLC_TOTAL_ORDERS`, `DFPLC_TOTAL_SPENT`, `DFPLC_RFM_R`, `DFPLC_RFM_F`, `DFPLC_RFM_M`, `DFPLC_LAST_ORDER`.

### Mailchimp

1. In Mailchimp, go to **Account > Extras > API keys**, create a key.
2. Find the **List ID** of your audience (in **Audience > Settings > Audience name and defaults**).
3. In the plugin, paste the key and the list ID.
4. Click **Test connection**.

Mailchimp limits merge field names to 10 characters. The plugin therefore uses shortened names: `DFPLTV` (predicted LTV), `DFCONF` (confidence), `DFCHURN` (churn), `DFSEG` (segment), `DFORDERS`, `DFSPENT`, `DFRFM` (concatenation of R+F+M as a 3-digit number).

### Klaviyo

1. In Klaviyo, go to **Account > Settings > API Keys**, create a **Private API Key** with the scopes _Profiles: Full Access_ and _Lists: Full Access_.
2. Optional: retrieve the ID of the list (visible in the URL `/list/`) if you want the plugin to subscribe contacts.
3. In the plugin, paste the key and optionally the list ID.
4. Click **Test connection**.

## Understanding the predictive model

### The probability that the customer is still active

The plugin computes `p_alive = exp(-days_since_last / expected_interval)`, where `expected_interval` is the average interval between two orders for this customer (or the store baseline if they only have one order). This formula decays exponentially: the more time passes since the last order, the higher the probability that the customer is "lost". Churn probability is simply `(1 - p_alive) × 100`.

### The predicted LTV

The formula is: `predicted_ltv = total_spent + p_alive × expected_future_orders × avg_aov_customer`. For a new customer (single order), the plugin uses the store baseline to estimate future orders. For a customer with multiple orders, it extrapolates their personal rhythm over a one-year horizon.

### Confidence

The confidence score combines two components: the quality of the personal history (the more orders a customer has, the better) and the richness of the store baseline (the more data the store has, the better). The formula weights `0.6 × history_score + 0.4 × baseline_score`.

For a new customer whose first order is less than 30 days old, churn probability is neutralized around 50% to avoid false positives. No reliable signal yet says whether they will return or not.

## The 9 business segments

The plugin places each customer into exactly one segment following a descending priority logic. Thresholds use the RFM quintiles (percentiles 20, 40, 60, 80) computed on your real base.

- **Champions**: customer with R ≥ 4, F ≥ 4 and M ≥ 4. Top RFM to retain.
- **High-value at risk**: predicted LTV ≥ p80 but R ≤ 3 and churn ≥ 40%. Critical alert signal.
- **Churn risk**: churn ≥ 70% and M ≥ 3. Valuable customer drifting away.
- **New customer**: 1 order and less than 30 days of tenure.
- **Potential loyalist**: 2 or more orders, R ≥ 4. On the verge of becoming loyal.
- **Loyal**: F ≥ 4 but M ≤ 3. Recurring but small basket.
- **Dormant**: R ≤ 2 and F ≥ 2. Was good, is not anymore.
- **Lost**: R = 1 and churn ≥ 90%. Lost, probably definitively.
- **Low value**: predicted LTV ≤ p25. Low economic potential.

If your store has fewer than 20 scored customers, segmentation falls back to "default" mode and simply assigns _new_customer_ or _loyal_ based on order count. Quintiles are only statistically significant beyond this threshold.

## Using the admin dashboard

### Dashboard

Synthetic view with four KPIs: total number of scored customers, average predicted LTV, average churn rate, size of the export queue. Below, the distribution by segment is displayed as colored bars, with the associated legend. The store baseline is visible at the bottom: repeat rate, average basket, average interval between orders.

### Customers

Paginated list with segment filters, sortable by predicted LTV, churn, order count or last order date. Each row shows the email, segment (with colored pill), predicted LTV, confidence, churn percentage, RFM score, order count, total spent and last order date.

### Exports

One panel per configured ESP, with two actions: **Test connection** to verify credentials, and **Sync all customers** to queue the entire base to that ESP. A global **Process queue** button lets you force immediate processing (without waiting for the hourly cron).

### Settings

General configuration (real-time recalc, auto-export, segments to auto-export, churn and high-value thresholds) then one panel per ESP with API key and list ID.

## Scheduled tasks

The plugin schedules two WP-Cron tasks as soon as it activates.

- `dfplc_daily_recalculation`: runs every day at 3:00 AM. Recalculates the store baseline, refreshes RFM quintiles, and re-scores up to 500 customers whose score is more than 24 hours old.
- `dfplc_hourly_export`: runs every hour. Pops 100 rows from the export queue and pushes data to the configured ESPs. Failed rows are retried up to 3 times before being marked as permanently failed.

If you use a system cron (via `wp-cron.php --disable_wp_cron`), make sure your schedule calls WordPress at least once per hour, otherwise the export queue will pile up.

## REST API

The plugin exposes a full REST namespace `dfplc/v1`, protected by the `manage_woocommerce` capability. Usable for external dashboards, automation scripts, or BI dashboards.

- `GET /wp-json/dfplc/v1/stats`: global statistics (totals, segment distribution, export queue, baseline).
- `GET /wp-json/dfplc/v1/customers`: paginated list of scored customers with filters and sorting.
- `POST /wp-json/dfplc/v1/recalculate`: triggers a batch recalc.
- `POST /wp-json/dfplc/v1/exporter/{provider}/test`: tests an ESP connection.
- `POST /wp-json/dfplc/v1/exporter/{provider}/sync-all`: queues the entire base to an ESP.
- `POST /wp-json/dfplc/v1/queue/process`: forces processing of the export queue.

Authentication uses a `wp_rest` nonce for calls from the WordPress admin, or standard WordPress REST authentication (Application Passwords, JWT, etc.) for external calls.

## Multilingual and translation

The plugin ships with five translation catalogs: French, English, Spanish, German and Italian. The textdomain is `dfpredictivectvchurn`. The `.po` files are located in `languages/`; you can edit them with Poedit or Loco Translate to add other languages or customize certain strings.

Loco Translate automatically generates the compiled `.mo` files on every save. This is the easiest method if you are not comfortable with the command line.

## Uninstallation

The `uninstall.php` file is automatically triggered by WordPress when you delete the plugin from the **Plugins** screen. It performs the following operations:

- Drops the 3 custom tables (`dfplc_customer_scores`, `dfplc_export_queue`, `dfplc_baseline`)
- Deletes all options prefixed with `dfplc_`
- Deletes the `dfplc_quintiles` transient
- Unschedules both WP-Cron tasks

No residual data remains after uninstallation.

## Troubleshooting

### "Scores are not updating"

Verify that WP-Cron is active (`DISABLE_WP_CRON` option not defined in `wp-config.php`) or that a system cron is calling `wp-cron.php` regularly. You can also force a manual recalc from the dashboard.

### "The export queue keeps growing"

Test the connection of each configured ESP. If the API key is expired or revoked, calls fail silently in the cron. Check the `last_error` column of the `wp_dfplc_export_queue` table to identify the exact cause.

### "My numbers look inconsistent"

Make sure the baseline has been recalculated after your initial scoring. If you imported a large batch of historical orders, force a full recalc from the dashboard to refresh all statistics.

## Resources

- Technical support: [datafirefly.com/support](https://www.datafirefly.com/support/)
- Commercial contact: [contact@datafirefly.com](mailto:contact@datafirefly.com)
- Full changelog: see the product sheet