Retention and erasure.

Use retention to limit raw activity history. Use erasure when every package record for one subject must be removed.

Configure raw-event retention

Set the number of days in config/customer-health.php:

'retention_days' => 90,

The default null keeps raw events forever. An integer of 0 makes every event older than the current UTC time eligible for pruning.

The cutoff is exclusive. An event exactly 90 days old is kept until it becomes older than the cutoff.

Prune raw events

ProductEventRecord uses Laravel's MassPrunable concern. Run the standard model pruning command for that model:

php artisan model:prune \
  --model='ByRcsc\LaravelCustomerHealth\Models\ProductEventRecord'

Add that command to Laravel's scheduler at the cadence required by the application. The package does not register a pruning schedule.

Pruning deletes only rows from customer_health_events. It keeps milestones, onboarding completion, score history, and current summaries.

Account for score windows

RecentActivity, FeatureActivity, and DistinctActors read raw events. Their results can fall after relevant events are pruned.

Keep retention_days at least as long as the longest activity window used by a registered score. The recompute command warns when retention is shorter, but it cannot restore deleted activity.

FeatureAdopted and OnboardingProgress read milestones, so raw-event pruning does not reverse those signals.

Erase one subject through PHP

CustomerHealth::purge($team);

This removes the subject's raw events, milestones, score history, and current summary for the tenant ID returned by the configured resolver.

Calling purge() again is safe. The method returns void whether or not rows existed.

Erase one subject through Artisan

Pass the stored morph class or alias and model key:

php artisan customer-health:purge team 42

For landlord summaries, override the tenant ID matched by the delete:

php artisan customer-health:purge team 42 --tenant=tenant-42

The command first resolves the subject model and confirms it implements Trackable. It fails without deleting when the identity cannot be resolved.

The --tenant option changes only which landlord summary row is removed. History deletion still uses the resolved subject identity on the configured package connection.

Understand transaction boundaries

When history and summaries use the same database connection, erasure happens in one transaction.

When they use different connections, history and summary deletion occur in separate transactions. A failure between them can leave partial erasure. Record the operation and retry it after fixing the failed connection.

The package does not delete the application subject model. It also does not delete related records outside its four configured tables.

What to read next

• Database storage for the rows retained or removed by each operation.
• Recomputing scores to rebuild missing summaries.
• Production operations to schedule pruning and monitor failures.