Configuration

Every setting on Settings -> Plugins -> Klaviyo Connect, in the order the page shows them, with the key that sets it from config/klaviyoconnect.php.

Klaviyo account#

The Sites table has one row per site. Enter keys as environment variables, such as $KLAVIYO_PRIVATE_API_KEY, to keep them out of project config. To share one Klaviyo account across sites, enter the same variable names in each row. To use a separate account for a site, give that row its own variables.

A site with a blank cell uses the value of that config key from config/klaviyoconnect.php, and the table shows which keys the file sets. After an upgrade from a version before 7.3, the single account saved before the upgrade fills every row.

When a queued send fails, Connection shows the error Klaviyo returned and its date. The error clears after a connection check where every site with a Private API Key connects.

Lists#

If a site’s lists cannot load, saving the page keeps that site’s chosen lists. For when lists refresh, see refresh the lists.

To set lists for every site from the config file, use klaviyoAvailableLists with an array of list IDs, or '*' for every list. A site with its own lists chosen ignores that key.

Tracking#

Exclude URI patterns#

For the pattern format, see exclude pages.

In the config file, each row is an array with uriPattern, siteUid (blank for all sites) and enabled.

Profile mapping#

These two tables appear under Tracking, after Sync Users in These Groups. Email comes from the user, or from the order on order events. First and last name come from the user.

Each row’s Source is a user field, User ID, or Twig value:

• A user field with an empty value is not sent, so the value already in Klaviyo stays.
• A Twig value gets user, and order on order events. Templates render in Craft’s Twig sandbox when the enableTwigSandbox config setting is on. Saving fails on a Twig syntax error. If a template throws an error when it renders, Klaviyo Connect skips that attribute and logs a warning.

In the config file, profileAttributeFields is keyed by external_id, phone_number, organization, title, locale or image. Each value is ['userField' => 'fieldHandle'], ['userField' => '__userId__'], or ['userField' => '__twig__', 'twig' => '...']. profileCustomProperties is a list of the same arrays, each with a name.

Event data#

Category and Brand each come from a relation or option field (related titles or option labels), the Product type name, Custom text, or a Twig value that gets product and variant. Brand also accepts a plain text field. Custom text and Twig categories can be comma-separated. Saving fails on a Twig syntax error, and a template that fails when it renders is skipped and logged. In the config file, set categoryField or brandField to __productType__, __custom__ (with categoryText or brandText) or __twig__ (with categoryTwig or brandTwig).

Catalog Item ID is what Viewed Product and order line items send as ProductID: the product ID (the default), the variant ID, or the variant SKU (productId, variantId or variantSku). Klaviyo matches ProductID to the item ID in your product catalog, so choose the ID that product type’s catalog feed uses. A variant without a SKU sends its variant ID.

In the config file, productTypeFields is keyed by product type UID or handle. Each value is an array with catalogItemId, productImageField, variantImageField, categoryField and brandField. To send the same brand for every product of a type, set brandField to __custom__ and brandText to the brand.

Config file#

A key set in config/klaviyoconnect.php overrides the value saved in the control panel. The Sites table and list keys are the exception: they fill only blank cells, unless the file sets siteSettings.

<?php

return [
    // Fill blank cells in the Sites table
    'klaviyoSiteId' => '$KLAVIYO_PUBLIC_API_KEY',
    'klaviyoApiKey' => '$KLAVIYO_PRIVATE_API_KEY',
    'cartUrl' => 'cart',
    'eventPrefix' => '',

    'klaviyoAvailableLists' => '*',

    'injectOnsiteScript' => true,
    'excludedUriPatterns' => [
        ['uriPattern' => '^checkout/payment', 'siteUid' => '', 'enabled' => true],
    ],
    'trackCommerceStartedCheckout' => true,
    'trackCommerceAddedToCart' => true,
    'trackCommerceCartUpdated' => true,
    'trackCommerceOrderCompleted' => true,
    'trackCommerceStatusUpdated' => true,
    'fulfilledOrderStatuses' => ['shipped'],
    'cancelledOrderStatuses' => ['cancelled'],
    'trackCommerceRefunded' => true,
    'klaviyoAvailableGroups' => [1],

    'profileAttributeFields' => [
        'external_id' => ['userField' => '__twig__', 'twig' => '{{ siteUrl }}{{ user.id }}'],
        'phone_number' => ['userField' => 'phone'],
    ],
    'profileCustomProperties' => [
        ['name' => 'Company Size', 'userField' => 'companySize'],
    ],

    'sendAddresses' => true,
    'sendCategories' => true,
    'sendPricingDetail' => true,
    'sendSiteContext' => true,
    'productTypeFields' => [
        'clothing' => [
            'catalogItemId' => 'variantSku',
            'productImageField' => 'productImage',
            'variantImageField' => 'variantImage',
            'categoryField' => 'productCategories',
            'brandField' => '__custom__',
            'brandText' => 'Acme',
        ],
    ],
    'imageEngine' => 'craft',
    'productImageFieldTransformation' => '',
    'imageWidth' => 600,
    'imageFit' => 'crop',
];

To set one site’s values from the file, use siteSettings, keyed by site UID. Each site’s array accepts klaviyoSiteId, klaviyoApiKey, cartUrl, eventPrefix and klaviyoAvailableLists. Setting siteSettings in the file replaces every row the control panel saved.