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

Line Item Events

Coupon Events

Address Events

Customer Events

Shipping Events

Order Events

Payment Events

Email Events

Checkout Events

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:

{# 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:

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:

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:

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

• $order - The Commerce Order element
• $type - An EventType enum case
• $payload - Extra data stored in the snapshot's payload key
• $message - 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:

'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 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:

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 - Viewing events in the control panel
• Statistics - Per-order timing statistics
• Services API - Programmatic access to log data