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-timed 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 different cartridge and different 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
When you're ready to start integrating, please reach out to us here to get connected with a representative on our end to review Klaviyo and pass along the cartridge for your framework.
Site Genesis (SG) Cartridge
The cartridge can be added via either Commerce Cloud Studio or Business Manager
Commerce Cloud Studio Cartridge Installation
- First, import the cartridge by selecting
int_klaviyo
on the import screen. - Next, link the cartridge to your sandbox. Select the Salesforce Commerce Cloud connection and select Properties then Project References and check in
int_klaviyo
.
Business Manager Cartridge Installation
- First, navigate to Administration > Import > General > Existing Projects into Workspace.
- Select the
int_klaviyo
directory from provided Klaviyo cartridge. - Install the cartridge.
Add the Cartridge to the Cartridge List
Once the cartridge is imported, it needs to be added to the list of cartridges in your site.
- Navigate to the Business Manager: Administration > Sites > Manage Sites.
- Select your site then select the Settings tab.
- At the end of the cartridge path, add
int_klaviyo
.
Import services XML file
In order to start tracking events and list signups, you’ll need to import the services file that comes with the cartridge (int_klaviyo\metadata\klaviyo-services.xml
) into the Business Manager. This creates the service definitions for the Klaviyo Track API and server-side Lists API.
- Navigate to Administration > Operations > Import and Export > Services.
- Upload and import the klaviyo-services.xml file.
This will create three services:
- KlaviyoSubscriptionService
- KlaviyoTrackService
- KlaviyoCheckSubscriptionService
For the KlaviyoSubscriptionService and KlaviyoCheckSubscriptionService, replace the ID in the service URL with the Klaviyo List ID that you will be using to subscribe users. For example, the import file will have the service URL as https://a.klaviyo.com/api/v2/list/LIST_ID/members. Replace the LIST_ID with the List ID of your newsletter list in Klaviyo.
Import custom attribute XML file
In order to start tracking events and list signups, you’ll need to import the metadata file (int_klaviyo\metadata\custom_atribute_klaviyo.xml
). This creates site-level custom attributes for storing the Klaviyo public and private API keys.
- Navigate to Administration > Site Development > Import and Export.
- Under the metadata section, upload and import the
custom_atribute_klaviyo.xml
file.
This creates the following attributes in Site Preferences:
- Klaviyo Account: This is your public API key used for sending events and profile data.
- Klaviyo API Key: This is the private API key used for sending list subscriptions.
- Klaviyo Enabled: This enables the Klaviyo Service.
Storefront Reference Architecture (SFRA) Cartridge
The cartridge can be added via either Commerce Cloud Studio or Business Manager.
Commerce Cloud Studio Cartridge Installation
- First, import the cartridge by selecting
plugin_klaviyo
on the import screen. - Next, link the cartridge to the sandbox. Select the Salesforce Commerce Cloud connection and select Properties. Select Project References and check in
plugin_klaviyo
.
Business Manager Cartridge Installation
- First, navigate to: Administration > Import > General > Existing Projects into Workspace.
- Select the
plugin_klaviyo
directory from provided Klaviyo cartridge. - Install the cartridge.
Add the Cartridge to the Cartridge List
Once the cartridge is imported, it needs to be added to the list of cartridges in your site.
- Navigate to the Business Manager: Administration > Sites > Manage Sites.
- Select your site then select the Settings tab.
- At the end of the cartridge path, add
plugin_klaviyo
.
Import Services XML File
In order to start tracking events and list signups, you’ll need to import the services file that comes with the cartridge (plugin_klaviyo\metadata\klaviyo-services.xml
) into the Business Manager. This creates the service definitions for the Klaviyo Track API and server-side Lists API.
- Navigate to Administration > Operations > Import and Export > Services.
- Upload and import the
klaviyo-services.xml
file.
This will create three services:
- KlaviyoSubscriptionService
- KlaviyoTrackService
- KlaviyoCheckSubscriptionService
For the KlaviyoSubscriptionService and KlaviyoCheckSubscriptionService, replace the ID in the service URL with the Klaviyo List ID that you will be using to subscribe users. For example, the import file will have the service URL as https://a.klaviyo.com/api/v2/list/LIST_ID/members. Replace the LIST_ID with the List ID of your Newsletter list in Klaviyo.
Import Custom Attribute XML File
In order to start tracking events and list signups, you’ll need to import the metadata file (plugin_klaviyo\metadata\custom_atribute_klaviyo.xml
). This creates site-level custom attributes for storing the Klaviyo public and private API keys.
- Navigate to Merchant Tools > Administration >Site Development->Import and Export.
- Under the metadata section, upload and import the
custom_atribute_klaviyo.xml
file.
This creates the following attributes in Site Preferences:
- Klaviyo Account: This is your public API key used for sending events and profile data.
- Klaviyo API Key: This is the private API key used for sending list subscriptions.
- Klaviyo Enabled: This enables the Klaviyo Service.
Add Integration-Enablement Snippets
Site Genesis Installation
- Add the following code to the end of your
minicart.isml
file:<isif condition="${pdict.CurrentHttpParameterMap.cartAction == 'add' || pdict.CurrentHttpParameterMap.cartAction == 'update'}"> <isinclude url="${URLUtils.url('Klaviyo-RenderKlaviyoAddToCart')}"/> </isif>
- Add the following code to your
footer_UI.isml
file after the includes forjquery-1.11.1.min.js
&jquery-ui.min.js
:<script src="${URLUtils.staticURL('/js/klaviyoFooterUtils.js')}"></script>
- Add the following code to the end of your
footer_UI.isml
file:<isinclude url="${URLUtils.url('Klaviyo-RenderKlaviyo', 'title', request.pageMetaData.title, 'pagecontexttype', ('pageContext' in this && !empty(pageContext)) ? ''+pageContext.type : null, 'pagecontexttitle', ('pageContext' in this && !empty(pageContext)) ? ''+pageContext.title : null, 'searchterm', request.httpParameterMap.q.stringValue, 'searchresultscount', (!empty(pdict.ProductSearchResult) ? ''+pdict.ProductSearchResult.count : null), 'productid', (!empty(pdict.Product) ? pdict.Product.ID : null), 'pagecgid', request.httpParameterMap.cgid.stringValue, 'orderno', (!empty(pdict.Order) ? pdict.Order.orderNo : null) )}" />
- Change the storefront controllers cartridge name to your cartridge name wherever referenced in the
Klaviyo.js
andEmailUtils.js
files. For example, in line 5 of theKlaviyo.js
file, replace theapp_controllers
with your controller cartridge name.
Storefront Reference Architecture Installation
- Add the following code to the
AddProduct
function in theCart.js
controller file, just before theres.json({……});
if(dw.system.Site.getCurrent().getCustomPreferenceValue('klaviyo_enabled')){ var KlaviyoUtils = require('*/cartridge/scripts/utils/klaviyo/KlaviyoUtils'); KlaviyoUtils.trackAddToCart(); }
- Add the following code to the end of
pageFooter.isml
file:<isscript> var KlaviyoUtils = require('*/cartridge/scripts/utils/klaviyo/KlaviyoUtils'); var context = KlaviyoUtils.getContext(); </isscript> <isinclude url="${URLUtils.url('Klaviyo-RenderKlaviyo', 'title', request.pageMetaData.title, 'pagecontexttype', (!empty(context)) ? ''+context : null, 'pagecontexttitle', ('pageContext' in this && !empty(pageContext)) ? ''+pageContext.title : null, 'searchterm', request.httpParameterMap.q.stringValue, 'searchresultscount', (!empty(pdict.productSearch) ? ''+pdict.productSearch.count : null), 'productid', (!empty(pdict.product) ? pdict.product.id : null), 'pagecgid', request.httpParameterMap.cgid.stringValue, 'orderno', (!empty(pdict.order) ? pdict.order.orderNumber : null) )}"/>
- Add the following code to
homepage.isml
and remove the existing subscription form code. The below code will render a subscription form.<iscomponent pipeline ="Klaviyo-FooterSubscribe" />
Enable OCAPI Integration
Endpoints
In order to integrate with SFCC for product catalog and historic order data, Klaviyo makes use of two OCAPI endpoints:
/order_search
: Syncs historical order data to Klaviyo and continues to sync ongoing order events every 30 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.
/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
- 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 the OCAPI.
- Once the API client is added, navigate to Administration > Open Commerce API Settings (under Site Development) in the SFCC Business Manager.
- For the below snippets, expose the API to only a specified client ID by substituting
API_VERSION
for your OCAPI version (currently 19.5 but we can use 18.8 as well) and replacing theCLIENT_ID
with the API Client ID (should look something like "xxxx-xxxx-xxxx-xxxx-xxxx"). Please note that the OCAPI version is reflected in the URL you call as well.If the client already has an OCAPI setting, only add the highlighted sections below to the existing
clients
JSON array.shop
and contextGlobal (Organization Wide)
.
Add the following JSON under the type{ "_v":"API_VERSION", "clients":[ { "client_id":"CLIENT_ID", "resources":[ { "resource_id":"/order_search", "methods":[ "post" ], "read_attributes":"(**)", "write_attributes":"(**)" } ] } ] }
data
and contextGlobal (Organization Wide)
.
{ "_v":"API_VERSION", "clients":[ { "client_id":"CLIENT_ID", "resources":[ { "resource_id":"/product_search", "methods":[ "post" ], "read_attributes":"(**)", "write_attributes":"(**)" } ] } ] }
Klaviyo-side Setup
- Navigate directly to the SFCC integration page in your account and add the following data:
- Store Name: your website domain (example.com)
- This will be the domain to create the URL from, so for the dev site it would be something like
dev03-na01-example.demandware.net
- This will be the domain to create the URL from, so for the dev site it would be something like
- Site Id: your demandware store name (usually company name)
- Auth token: create an Auth Token for this integration that will be used to request a bearer token
- Store Name: your website domain (example.com)
Test your SFCC Integration
To test out your plugin, 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
- Go to the checkout page
- 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 events.
Review and Understand Your Salesforce Commerce Cloud Data
The Salesforce Commerce Cloud integration will enable tracking of the following datapoints:
- Searched Site: Event fired when someone initiates a search.
- Viewed Product: Event fired when someone views a product page.
- Viewed Category: Event fired when someone views a category page.
- Added to Cart: Event fired when someone adds/modifies their cart.
- Started Checkout: Event fired when someone initiates a checkout.
- Placed Order: Event fired when the someone places an order (wholistic order data).
- Ordered Product: Event(s) fired when the someone places their order (specific product data).
In addition to these events, when a customer subscribes to your mailing list via a default SFCC subscription form, they will be added to the list designated by the LIST_ID entered in the Import services XML file step.