How to integrate with Salesforce Commerce Cloud

You will learn

Learn how to integrate Salesforce Commerce Cloud with Klaviyo. 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:

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

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

Before you begin

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 in this article 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

1. In your IDE, such as Eclipse, navigate to Administration > Import > General > Existing Projects into Workspace.
2. Import the int_klaviyo_core directory using the import wizard.
3. Select the SFCC instance with which to connect the cartridge.
4. Select Properties.
5. Select Project References.
6. Check in the int_klaviyo_core cartridge.
7. 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.

1. Navigate to Administration > Sites > Manage Sites.
2. Select your site.
3. Select the Settings tab.
4. 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).
5. 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.

1. Navigate to Administration > Site Development > Site Import & Export > Services.
2. Upload then import metadata.zip file.
   
   
3. When you're prompted to confirm whether you'd like to import the selected archive, select OK.
4. You should now see the import running under the Status section near the bottom of the page.
   
5. 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.
6. 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).
   
7. 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

1. Add the following code to the bottom of your footer_UI.isml file:

   <isinclude template="components/footer/klaviyoFooter"/>

2. 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

1. Add the following code to the bottom of your pageFooter.isml file:

   <isinclude template="klaviyo/klaviyoFooter"/>

2. 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.

SFCC-side setup

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

1. 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.
2. Once the API client is added, navigate to Administration > Site Development > Open Commerce API Settings in the SFCC Business Manager.
3. 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.
   1. 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:
      

   2. 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

1. Navigate to the SFCC integration page in your account (found under Account name > Integrations > All Integrations, then search for Salesforce Commerce Cloud) 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).
2. 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.
   
3. 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:

1. 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.
2. Search your catalog.
3. View a category page.
4. View a product page.
5. Add an item to your cart.
6. Place a test order.
7. Navigate Analytics > Metrics in Klaviyo, then look for metrics coming from Salesforce Commerce Cloud.

Outcome

You've now integrated Salesforce Commerce Cloud with Klaviyo and tested your integration.

Additional resources 

• Salesforce Commerce Cloud data reference
• How often integrations sync reference