WP WordPress WordPress & WooCommerce Intermediate

Predictive LTV & Churn — Full documentation

Installation, configuration and usage guide for the predictive LTV scoring and automatic RFM segmentation plugin for WooCommerce.

Updated Module version 1.0.0

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/<LIST_ID>) 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

Was this page helpful?

Still stuck? Contact support