How to Integrate with Salesforce Commerce Cloud – Klaviyo - Help Center

Overview

The Klaviyo Cartridge and API integration allows websites using Salesforce Commerce Cloud (formerly Demandware) to quickly connect and send both real-time and historic data to Klaviyo. When Salesforce Commerce Cloud (SFCC) is integrated, Klaviyo will start tracking actions people take in real-time like website navigation, search tracking, viewing products, viewing categories, adding items to a cart, checking out, and ordering.

There are three main steps to integrating Salesforce Commerce Cloud (SFCC) with Klaviyo:

Installing the Klaviyo Cartridge in SFCC.
Adding enablement snippets to SFCC.
Enabling the SFCC OCAPI integration in Klaviyo.

This guide covers these steps and the related tasks for integrating SFCC stores.

Klaviyo integrates with both SFCC Controller-based Site Genesis (SG) and Storefront Reference Architecture Site Genesis (SFRA). Each framework requires a slightly different cartridge setup and snippets described below.

If you'd like to start by integrating your development environment first, you can create a linked Klaviyo account using the method described here and connect your development environment with that account. We recommend including the word "Dev" or "Staging" in the company name you use when setting up the account in order to better differentiate between the accounts when logged in.

Cartridge Setup

The Klaviyo cartridge setup consists of three main cartridges due to the nature of SFCC's different infrastructures. These cartridges include:

int_klaviyo: for SiteGenesis-based websites
int_klaviyo_sfra: for SFRA-based websites
int_klaviyo_core: for both types of infrastructure, containing some basic, overlapping functionality

You will only need to use two of the three cartridges provided, int_klaviyo_core and the cartridge specific to the framework of your SFCC website. Both your relevant cartridge and the core cartridge are required for the integration to work correctly.

You can find our cartridges in a zip archive available for download on the Commerce Cloud XChange.

Import the Cartridges

The first step is to import the cartridges in Eclipse so they're available to link with your SFCC instance

In your IDE, such as Eclipse, navigate to Administration > Import > General > Existing Projects into Workspace.
Import the int_klaviyo_core directory using the import wizard.
Select the SFCC instance with which to connect the cartridge.
Select Properties.
Select Project References.
Check in the int_klaviyo_core cartridge.
Repeat steps 2 through 6 for the other cartridge specific to your framework (either int_klaviyo or int_klaviyo_sfra).

Add the Cartridges to the Cartridge Path

Once the cartridges are imported, they need to be added to the list of cartridges used by your site using SFCC's Business Manager.

Navigate to Administration > Sites > Manage Sites.
Select your site.
Select the Settings tab.
At the end of the cartridge path input labelled Cartridges, add the names of the imported Klaviyo cartridges with the core cartridge last (either, int_klaviyo:int_klaviyo_core or int_klaviyo_sfra:int_klaviyo_core).
Click Apply.

Once you've clicked Apply, you should now see the two cartridges at the end of the field labelled Effective Cartridge Path.

Add Services

After importing the cartridges and adding them to the site cartridge path, the Klaviyo service must be added to enable settings configuration for the cartridge. In the root directory of the Klaviyo cartridges zip file is another zip file called metadata.zip. The following directions will reference this zip file.

Navigate to Administration > Site Development > Site Import & Export > Services.
Upload then import metadata.zip file.
When you're prompted to confirm whether you'd like to import the selected archive, select OK.

You should now see the import running under the Status section near the bottom of the page.

You will now have access to a preferences page at Merchant tools > Site Preferences > Custom Preferences > klaviyo.

from which you can manage the following settings:

Klaviyo Enabled: Must be set to "Yes" to enable the cartridge
Klaviyo Private Key: Your Klaviyo Private API Key
Klaviyo Account: Your Klaviyo Public API Key/Account ID
Image Type: The product image type you would like the to be used in event data sent to Klaviyo

If you're not sure which Image Type to set, navigate to Merchant tools > Products and Catalogs > Products, click on a product, and determine which view type you would want to use based on what's available (eg. large, medium, small, hi-res).

The metadata.zip file will also create a new service in SFCC. Navigating to Administration > Operations > Services, you should now see a new entry under the Services, Profiles, and Credentials tabs called KlaviyoTrackService, KlaviyoTrackProfile, and KlaviyoTrackCredentials, respectively.

Add Snippets

The last part of the cartridge setup is to add some snippets to website template files in order to enable the cartridge to communicate with the site. These steps differ slightly for Site Genesis (SG) and Storefront Reference Architecture (SFRA) infrastructures so make sure to follow the instructions for your setup.

Site Genesis

Add the following code to the bottom of your footer_UI.isml file:
```
<isinclude template="components/footer/klaviyoFooter"/>
```

Include the following in the minicart.isml, cart.isml and any other "cart" isml files the site uses:

<isif condition="${pdict.CurrentHttpParameterMap.cartAction == 'add' || pdict.CurrentHttpParameterMap.cartAction == 'update'}">
  <isinclude url="${URLUtils.url('Klaviyo-RenderKlaviyoAddToCart')}"/>
</isif>

Storefront Reference Architecture

Add the following code to the bottom of your pageFooter.isml file:
```
<isinclude template="klaviyo/klaviyoFooter"/>
```

Add the following code to the AddProduct function in the Cart.js controller file, just before the line with res.json({...});:

if(dw.system.Site.getCurrent().getCustomPreferenceValue('klaviyo_enabled')){
  var KlaviyoUtils = require('*/cartridge/scripts/utils/klaviyo/klaviyoUtils');
  KlaviyoUtils.trackAddToCart();
}

Enable OCAPI Integration

Endpoints

In order to integrate with SFCC for product catalog and historic/ongoing order data, Klaviyo makes use of three OCAPI endpoints:

/order_search: Syncs historical order data to Klaviyo and continues to sync ongoing order events every 60 minutes. The Ordered Product and Placed Order events will sync additional data for segmentation and flow filtering, so is ideal for enhanced personalization not available from the Order Confirmation event.

For real-time order confirmation emails, use the Order Confirmation event from the cartridge.
/sites: Allows you to select from which site Klaviyo syncs data during your integration setup.
/product_search: Connects your catalog to Klaviyo to enable functionality/features including product recommendation blocks in emails.

If you have a product catalog of greater than 10,000 items, please tell your account representative before integrating your catalog, as the OCAPIs have limits, and you may require a configuration-level setting to limit sync rate.

Similarly, if you are unable to update your OCAPI to version 18.3, please let us know during integration discussions.

SFCC-side Setup

Before we can communicate with SFCC's OCAPI, some permissions and settings must be set up in SFCC.

Navigate to https://account.demandware.com/dw/account/APIAdmin and add an API client for Klaviyo. The API Client ID and password will be required to generate the bearer token for OCAPI.
Once the API client is added, navigate to Administration > Site Development > Open Commerce API Settings in the SFCC Business Manager.

Add the following snippets, replacing the API version and Client ID. We support API versions 19.5 and above as well as 18.8. Replace CLIENT_ID with the API Client ID generated from the API client setup in the previous step (this should look something like "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx").

If the settings already exist for these APIs, you may only need to add the highlighted sections below to the existing clients JSON array.

Add the following JSON under the type Shop and context Global (Organization Wide), replacing SHOP_API_VERSION with your OCAPI Shop API version, then click Save.

{
         "_v":"SHOP_API_VERSION",
         "clients":[
            {
             "client_id":"CLIENT_ID",
             "resources":[
              {
               "resource_id":"/order_search",
               "methods":["post"],
               "read_attributes":"(**)",
               "write_attributes":"(**)"
              }
             ]
            }
         ]
        }

Once added, the settings should appear similar to this:

Add the following JSON under the type data and context Global (Organization Wide), replacing DATA_API_VERSION with your OCAPI Data API version, then click Save.

{
     "_v":"DATA_API_VERSION",
     "clients":[
        {
         "client_id":"CLIENT_ID",
         "resources":[
          {
           "resource_id":"/product_search",
           "methods":["post"],
           "read_attributes":"(**)",
           "write_attributes":"(**)"
          },
          {
           "resource_id":"/sites",
           "methods":["get"],
           "read_attributes":"(**)",
           "write_attributes":"(**)"
          }
         ]
        }
     ]
    }

Once added, the settings should appear similar to this:

Klaviyo-side Setup

Navigate to the SFCC integration page in your account and add the following data:

Store URL: your website domain (eg. example.com or dev03-na01-example.demandware.net)
Auth token: create an auth token for this integration that will be used to request a bearer token. The auth token is generated by base-64 encoding the client ID and password joined by a colon (:) (eg. xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx:password).
Data API Version: The version of your Data API for which you added access in the SFCC-side Setup step (e.g. v19_10)
Shop API Version: The version of your Shop API for which you added access in the SFCC-side Setup step (e.g. v19_10)
Catalog ID: The ID of the SFCC catalog to sync with Klaviyo (eg. * or something more specific like storefront-catalog-en)

Once you've entered these credentials, click the "Click here to retrieve the list of sites" link to retrieve a list of sites on your SFCC instance.

After the sites are retrieved, select the site to integrate with this account and click "Connect to Salesforce Commerce Cloud".

Your integration should now start syncing your order, catalog, and customer data.

Test your SFCC Integration

To test out your cartridge setup, go to your website and follow these instructions:

Cookie yourself by adding the url parameter utm_email as your email address to your address bar. For example: https://www.example.com/?utm_email=your@email.com
Search your catalog
View a category page
View a product page
Add an item to your cart
Place a test order
Navigate to your Klaviyo Dashboard's Activity Feed or to the profile of the email you used to cookie yourself, you should see your actions begin to appear as metrics.

Additional Resources