Event Tracking beta

Order Lifecycle automatically tracks key events throughout an order's lifecycle in Craft Commerce. All tracking happens via Craft Commerce's native event system - no extra code is required for automatic events.

Automatically Tracked Events

Cart Events

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

Line Item Events

Event type	Trigger
lineItemAdded	Product added to cart
lineItemRemoved	Product removed from cart
lineItemUpdated	Quantity or options changed

Coupon Events

Event type	Trigger
couponApplied	Coupon code applied to cart
couponRemoved	Coupon code removed from cart

Address Events

Event type	Trigger
shippingAddressSet	Shipping address added or updated
shippingAddressRemoved	Shipping address removed
billingAddressSet	Billing address added or updated
billingAddressRemoved	Billing address removed

Customer Events

Event type	Trigger
customerSet	Customer email set on the order
customerRemoved	Customer email removed from the order

Shipping Events

Event type	Trigger
shippingMethodSet	Shipping method selected or changed

Order Events

Event type	Trigger
statusChanged	Order status changed
orderCompleted	Order marked as complete
orderPaid	Order fully paid

Payment Events

Event type	Trigger
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 type	Trigger
emailSent	Order email sent successfully
emailFailed	Order email failed to send

Checkout Events

Event type	Trigger
checkoutStarted	Customer visited the checkout page (manual - see below)

Manual Checkout Tracking

The checkoutStarted event is not automatic because Craft Commerce does not fire a native event when a customer visits the checkout page. Call it from your checkout template to record it once per order:

{# In your checkout template #}
{% do craft.orderLifecycle.logCheckoutStarted(cart) %}

The call is idempotent - if checkout has already been logged for that order, it does nothing.

You can also call it from PHP:

use johnhenry\orderlifecycle\OrderLifecycle;

OrderLifecycle::getInstance()->logger->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()->logger->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 generates a human-readable description of changes, 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 to automatically delete old records, 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)

Disable collection settings in Settings → Order Lifecycle if you need to minimise PII storage 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