README

Implements the Buy 'Til You Die model for customer lifetime value (CLV) prediction. Fits BG/NBD parameters (purchase frequency + churn) and Gamma-Gamma parameters (monetary value) using MLE via Nelder-Mead optimisation. Supports persisting fitted parameters to the database for reuse.

Installation

composer require centrex/laravel-btyd
php artisan vendor:publish --tag="laravel-btyd-migrations"
php artisan migrate

Usage

1. Build customer summaries from transaction history

use Centrex\Btyd\Btyd;

// Each transaction: ['date' => Carbon|string, 'amount' => float]
$transactions = [
    ['date' => '2024-01-15', 'amount' => 120.00],
    ['date' => '2024-03-02', 'amount' => 85.50],
    ['date' => '2024-06-18', 'amount' => 200.00],
];

$summary = Btyd::transactionsToSummary($transactions);
// returns: frequency, recency (days), T (days since first purchase), monetary, n_transactions, total_revenue

2. Fit the models on a cohort

$btyd = new Btyd();

// Fit BG/NBD on cohort summaries (frequency, recency, T required per customer)
$bgnbdParams = $btyd->fitBgNbd($cohortSummaries);
// returns: ['r' => ..., 'alpha' => ..., 'a' => ..., 'b' => ...]

// Fit Gamma-Gamma on customers with at least 1 repeat purchase (frequency, monetary required)
$ggParams = $btyd->fitGammaGamma($cohortSummaries);
// returns: ['p' => ..., 'q' => ..., 'v' => ...]

3. Predict for individual customers

// Expected number of transactions over the next 12 months
$expectedTx = $btyd->expectedTransactions($customerSummary, horizonMonths: 12);

// Expected monetary value per transaction
$expectedMonetary = $btyd->expectedMonetary($customerSummary);

// Customer lifetime value (expectedTx × expectedMonetary)
$clv = $btyd->customerClv($customerSummary, horizonMonths: 12);

4. Persist fitted parameters

use Centrex\Btyd\Models\BtydParam;

// Save fitted params for a given model class
BtydParam::updateOrCreate(
    ['model' => App\Models\Customer::class],
    ['params' => array_merge($bgnbdParams, $ggParams)],
);

// Load later
$params = BtydParam::getParams(App\Models\Customer::class);

Full workflow example

$btyd = new Btyd();

// Build summaries for all customers
$summaries = Customer::all()->map(fn ($c) =>
    Btyd::transactionsToSummary($c->orders->map(fn ($o) => [
        'date' => $o->created_at,
        'amount' => $o->total,
    ])->toArray())
)->toArray();

// Fit
$btyd->fitBgNbd($summaries);
$btyd->fitGammaGamma($summaries);

// Predict CLV for a single customer
$clv = $btyd->customerClv($summaries[0], 12);
echo "12-month CLV: {$clv}";

Testing

composer test        # full suite
composer test:unit   # pest only
composer test:types  # phpstan
composer lint        # pint

Changelog

Please see CHANGELOG for more information on what has changed recently.

Credits

• centrex
• All Contributors

License

The MIT License (MIT). Please see License File for more information.