---
title: Event Tracking
date: 2026-06-13T16:15:00+01:00
author: John Henry Donovan
canonical_url: "https://johnhenry.ie/plugins/order-lifecycle/docs/guide/event-tracking"
section: Plugins
---
esc

↑↓ to navigate↵ to selectesc to close

Menu On this page 

- [Return to top](#)

Documentation

Documentation

# Event Tracking

Order Lifecycle automatically tracks the key events throughout an order's lifecycle in Craft Commerce. All of this happens through Craft Commerce's native event system, so no extra code is needed for the automatic events.

## Automatically Tracked Events

### Cart Events

Event typeTrigger`cartCreated`New cart saved for the first time`cartUpdated`General cart save (line items, addresses, etc. changed)

### **Line Item Events**

Event typeTrigger`lineItemAdded`Product added to cart`lineItemRemoved`Product removed from cart`lineItemUpdated`Quantity or options changed

### Coupon Events

Event typeTrigger`couponApplied`Coupon code applied to cart`couponRemoved`Coupon code removed from cart

### Address Events

Event typeTrigger`shippingAddressSet`Shipping address added or updated`shippingAddressRemoved`Shipping address removed`billingAddressSet`Billing address added or updated`billingAddressRemoved`Billing address removed

### Customer Events

Event typeTrigger`customerSet`Customer email set on the order`customerRemoved`Customer email removed from the order

### Shipping Events

Event typeTrigger`shippingMethodSet`Shipping method selected or changed

### Order Events

Event typeTrigger`statusChanged`Order status changed`orderCompleted`Order marked as complete`orderPaid`Order fully paid

### Payment Events

Event typeTrigger`paymentAttempt`Payment attempt failed (successful first-try payments are not logged)`paymentProcessed`Payment successfully processed`paymentAuthorized`Payment authorized`paymentCaptured`Payment captured`paymentRefunded`Refund issued`paymentTransaction`Any transaction state change (requires "Log All Payment Transactions" enabled)

### Email Events

Event typeTrigger`emailSent`Order email sent successfully`emailFailed`Order email failed to send

### Checkout Events

Event typeTrigger`checkoutStarted`Customer visited the checkout page (manual - see below

## Manual Checkout Tracking

The `checkoutStarted` event isn't automatic, because Craft Commerce doesn't fire a native event when a customer visits the checkout page. Call it somewhere in your checkout flow to record it once per order:

```twig
{# Example only - add this wherever your checkout flow actually lives #}
{% set cart = craft.commerce.carts.cart %}
{% if cart and cart.email %}
  {% do craft.orderLifecycle.logCheckoutStarted(cart) %}
{% endif %}
```

There's no single "checkout template" every build uses - yours might be an address step, a cart/index template, or a single-page checkout partial. Add the tag wherever the customer first commits to checking out, not necessarily wherever this snippet implies.

The call is idempotent - if checkout has already been logged for that order, it won't do anything.

You can also call it from PHP:

```php
use johnhenry\orderlifecycle\OrderLifecycle;

OrderLifecycle::getInstance()->getLogger()->logCheckoutStarted($order);
// returns true if logged, false if already recorded
```

## Logging Custom Events

Use the logger service to record any business-specific event against an order:

```php
use johnhenry\orderlifecycle\OrderLifecycle;
use johnhenry\orderlifecycle\enums\EventType;

// Log with a custom message
OrderLifecycle::getInstance()->getLogger()->log(
    $order,
    EventType::STATUS_CHANGED,
    ['note' => 'Manually escalated by support'],
    'Order escalated to priority fulfilment'
);
```

The `log()` signature:

```php
public function log(
    Order $order,
    EventType $type,
    array $payload = [],
    ?string $message = null
): void
```

- `<strong>$order</strong>` - The Commerce Order element
- `<strong>$type</strong>` - An `EventType` enum case
- `<strong>$payload</strong>` - Extra data stored in the snapshot's `payload` key
- `<strong>$message</strong>` - Custom message. If `null`, a message is auto-generated by comparing the current order state to the last snapshot

## Auto-Generated Change Messages

When `$message` is `null`, the logger compares the current order snapshot to the previous one and puts together a human-readable description of what changed, for example:

```bash
'WIDGET-A' quantity increased from 1 to 3
Total price changed from 25.00 EUR to 49.99 EUR
Coupon code 'SAVE10' applied
Order status changed to 'processing'
Shipping method changed from Standard to Express
```

Multiple changes are joined with semicolons.

## Controlling What Is Tracked

Each event category has a corresponding toggle in **Settings → Order Lifecycle**. See [Configuration](https://johnhenry.ie/plugins/order-lifecycle/docs/getting-started/configuration) for the full list.

## Event Retention

By default logs are kept indefinitely. Set **Auto-Prune Logs After (Days)** in the plugin settings if you want old records deleted automatically, or run the purge command manually:

```bash
php craft order-lifecycle/logs/purge --days=90
```

## Privacy Considerations

Event logs may contain:

- Customer email addresses (in snapshots)
- IP addresses (if **Collect User IP Address** is enabled)
- User IDs (if **Collect User ID** is enabled)

Turn off the collection settings in **Settings → Order Lifecycle** if you need to keep PII storage to a minimum for GDPR or similar compliance.

## Next Steps

- [Timeline View](https://johnhenry.ie/plugins/order-lifecycle/docs/guide/timeline-view) - Viewing events in the control panel
- [Statistics](https://johnhenry.ie/plugins/order-lifecycle/docs/guide/statistics) - Per-order timing statistics
- [Services API](https://johnhenry.ie/plugins/order-lifecycle/docs/api/services) - Programmatic access to log data

On this page