Add properties with PHP events

How to add your own properties to the profiles and events Klaviyo Connect sends, from a Craft module or plugin.

The events#

Klaviyo Connect triggers four events on fostercommerce\klaviyoconnect\services\Track. Each one fires before the data is queued for Klaviyo, so a listener’s changes are part of the send.

The event classes are in the fostercommerce\klaviyoconnect\events namespace. The order and line item events need Craft Commerce.

Event names in these events do not include the site’s Event Prefix.

Example#

This module adds the amount paid to every order event, and the customer’s last order number to their profile when they place an order.

<?php

declare(strict_types=1);

namespace modules\klaviyo;

use craft\commerce\elements\Order;
use fostercommerce\klaviyoconnect\events\AddOrderCustomPropertiesEvent;
use fostercommerce\klaviyoconnect\events\AddProfilePropertiesEvent;
use fostercommerce\klaviyoconnect\services\Track;
use yii\base\Event;
use yii\base\Module as BaseModule;

class Module extends BaseModule
{
    public function init(): void
    {
        parent::init();

        Event::on(
            Track::class,
            Track::ADD_ORDER_CUSTOM_PROPERTIES,
            static function (AddOrderCustomPropertiesEvent $event): void {
                $event->properties['TotalPaid'] = $event->order->getTotalPaid();
            },
        );

        Event::on(
            Track::class,
            Track::ADD_PROFILE_PROPERTIES,
            static function (AddProfilePropertiesEvent $event): void {
                $order = is_array($event->context) ? ($event->context['order'] ?? null) : null;
                if ($event->event === 'Placed Order' && $order instanceof Order) {
                    $event->properties['LastOrderNumber'] = $order->number;
                }
            },
        );
    }
}

Register the listeners in your module’s init() method, as shown. For setting up a module, see Craft’s module guide.

Add profile properties#

Track::ADD_PROFILE_PROPERTIES fires each time Klaviyo Connect builds a profile to send:

• For an identify call, from the klaviyoconnect/api/identify and klaviyoconnect/api/track actions, or when a user in a selected user group is saved. event and context are null.
• For a custom event posted from a form. event is the event name and context is null.
• For an order event. event is the event name and context holds the order. A status change uses the name Klaviyo receives, such as Fulfilled Order. The Placed Order profile is also the profile for that order’s Ordered Product events.

Keep email in profile. Klaviyo Connect does not send an event or identify call for a profile without one.

Add order properties#

Track::ADD_ORDER_CUSTOM_PROPERTIES fires once for each order event: Started Checkout, Added to Cart, Updated Cart, Placed Order, order status changes and Refunded Order. It also fires for order events posted from forms and for past orders sent from the utility or the klaviyoconnect/orders/sync command.

properties starts with the order properties Klaviyo Connect sends. Add keys to the array rather than assigning a new one, because a new array replaces the built-in properties. To remove a built-in property, unset() its key.

use fostercommerce\klaviyoconnect\events\AddOrderCustomPropertiesEvent;
use fostercommerce\klaviyoconnect\services\Track;
use yii\base\Event;

Event::on(
    Track::class,
    Track::ADD_ORDER_CUSTOM_PROPERTIES,
    static function (AddOrderCustomPropertiesEvent $event): void {
        if ($event->event === 'Placed Order') {
            $event->properties['GiftMessage'] = $event->order->getFieldValue('giftMessage');
        }
    },
);

Add line item properties#

Track::ADD_LINE_ITEM_CUSTOM_PROPERTIES fires once per line item, each time Klaviyo Connect builds an order event’s properties. It fires before the order event, for the same event names.

properties starts with the line item properties Klaviyo Connect sends. As with order properties, add keys rather than assigning a new array.

The result becomes the line item’s entry in the order’s Items property, and the properties of its Ordered Product event. Changes to ProductName and Categories also change the order’s ItemNames and Categories.

A custom line item, which has no purchasable, starts with an empty properties array. Klaviyo Connect leaves a line item out of Items and does not send an Ordered Product event for it unless a listener adds properties.

use craft\commerce\elements\Variant;
use fostercommerce\klaviyoconnect\events\AddLineItemCustomPropertiesEvent;
use fostercommerce\klaviyoconnect\services\Track;
use yii\base\Event;

Event::on(
    Track::class,
    Track::ADD_LINE_ITEM_CUSTOM_PROPERTIES,
    static function (AddLineItemCustomPropertiesEvent $event): void {
        $purchasable = $event->lineItem->getPurchasable();
        if ($purchasable instanceof Variant) {
            $event->properties['Color'] = $purchasable->getFieldValue('color')?->label;
        }
    },
);

Add custom event properties#

Track::ADD_CUSTOM_PROPERTIES fires when a form posts an event to klaviyoconnect/api/track with an event[name] and without event[trackOrder]. For the form parameters, see actions.

use fostercommerce\klaviyoconnect\events\AddCustomPropertiesEvent;
use fostercommerce\klaviyoconnect\services\Track;
use yii\base\Event;

Event::on(
    Track::class,
    Track::ADD_CUSTOM_PROPERTIES,
    static function (AddCustomPropertiesEvent $event): void {
        if ($event->event === 'Requested Quote') {
            $event->properties['SalesRegion'] = 'West';
        }
    },
);

Errors in a listener#

If a listener throws an exception, Klaviyo Connect logs it to the klaviyoconnect log category and does not send that event. The request that triggered the event continues, so a failing listener does not stop checkout.

Placed Order is the exception. It is built in a queue job, for live orders and for past orders, so an exception fails the job. After fixing the listener, retry the job from Utilities -> Queue Manager.