Setting Up Loyalty & Referrals on SFCC Controllers and Pipelines

Yotpo’s suite of integrated solutions for loyalty and referrals helps commerce companies accelerate growth by enabling advocacy and maximizing customer lifetime value. With Yotpo's Loyalty and Referrals solutions, brands can effectively leverage social proof to increase trust and sales, cultivate loyal customer advocates, and make better business decisions based on real customer feedback.

This document provides a technical overview and step-by-step instructions for installing Yotpo's Salesforce Commerce Link Cartridge - enabling you to integrate various Yotpo features within a Salesforce Commerce storefront.

Merchants using Yotpo's Salesforce Commerce Link Cartridge can access the following features:

• Loyalty Program (Earning and redeeming points)
• Referral Program 

Cartridge overview

The Loyalty & Referrals integration makes use of the following cartridges: 

Terms of service

In using the Yotpo LINK cartridge, you agree to Yotpo's terms of service.

Step 1: Configuration

Files download

Make sure to download the installation files.

Cartridge registration

Navigate to the following path: Administration > Manage Sites  > Business Manager  >  Settings

Add the cartridge name: bm_yotpo within the Cartridges path as shown below:

The cartridge includes a custom interface within the Salesforce Business Manager to manage logins to the Yotpo Loyalty & Referrals control panel.

SiteGenesis Controller cartridge configuration

The Yotpo cartridge relies on a “guard” script from SiteGenesis Controller cartridge if the integration is being implemented with the Controller version. 

• The default name used in Salesforce is:  app_storefront_controllers
• If the controller cartridge name differs from the default name, you need to change the constant in Yotpo's code. This is the constant that needs to change; exports.SITEGENESIS_CARTRIDGE_NAME = "app_storefront_controllers";
• You need to change it in Yotpo's code under int_yotpo/cartridge/scripts/yotpo/utils/Constants.js

Uploading Metadata configurations

The downloaded files include a metadata.zip file that needs to be uploaded to your Salesforce admin. 

To upload the file, go to Administration > Site development > Import & Export > Manage Import Files and upload the metadata.zip file:

Once the file is uploaded, click the Import button next to "Meta data". You'll be guided through a Salesforce Commerce Cloud installation wizard.

This process automatically adds all the necessary Yotpo attributes to your platform.

Services details

In this section, we are defining where Yotpo's cartridge will send Salesforce information (such as orders, customers, etc) to Yotpo's backend. 

1. Navigate to Administration > Operations > Services > Click on the Credentials tab
2. Click New
   
3. In the Name field (Required) add the following: int_yotpo.https.post.swell.api.cred
4. In the URL field add: https://app.swellrewards.com/commerce-cloud/
   
5. User and Password fields are not required
6. Once the setting is saved, this is what you will see in Salesforce: 

Step 2: Setting up the integration

Adding logged-in customer and cart tracking

Yotpo Loyalty needs to have information about the customer on the website's front end. We need to know if the customer is logged in and we also need to know the cart information. We need this information in order to present the customer with their points balance, redemption options, etc. In order for Yotpo to get this information, the following template must be included within the storefront footer file i.e. footer.isml in SiteGenesis:

<isinclude template="include/yotpofooter" />

After you place the above html template snippet in your page (in the example below, it's in the footer), it will be rendered on your site as follows (swell customer identification and swell cart identification tags were added):

Adding Data Observers

Yotpo needs to get all orders and customers in order to be able to reward points, give coupons, place customers in tiers, etc. The loyalty cartridge is responsible for sending this information from SFCC to Yotpo by using two site genesis controllers described below. The details of controllers are described below.

Order observer

The order observer hook should be added into COSummary-Submit (checkout summary submit) controller after order creation with the following code snippet:

        var SwellExporter = require('int_yotpo/cartridge/scripts/yotpo/swell/export/SwellExporter');
        var result = SwellExporter.exportOrder({
            orderNo: order.orderNo,
            orderState: 'created'
        });

Customer observer

The customer observer hook should be added into Account-RegistrationForm and Account-EditForm controllers using the following code snippet:

        var SwellExporter = require('int_yotpo/cartridge/scripts/yotpo/swell/export/SwellExporter');
        var result = SwellExporter.exportCustomer({
               customerNo: customer.profile.customerNo
        });

After adding the above code snippet your controllers will look like this:

Account registration form

Account edit form

Adding Yotpo cartridge required endpoints

On top of orders and customers that Yotpo is listening to through the above controllers, Yotpo needs to get more information from the cartridge in order for the loyalty and referral program to perform properly. This step is crucial in the setup of the integration. 

In this section, we are mapping the methods required in the cartridge to URLs (endpoints) that will be available in SFCC for Yotpo to pull data. 

Steps to adding the required endpoints mapping

Navigate to Merchant Tools > SEO > URL Rules > Pipeline URLs  

Add the following mappings URLs in Pipeline URLs

After adding the endpoints, your setting page will look like this: 

Step 3: Setting up refunds

If you'd like to deduct or re-issue points redeemed at checkout for refunded orders, you'll need to send Yotpo Loyalty & Referrals the refund data. If you're using product-specific requirements or restrictions for campaigns, you'll also need to include specific item information along with the required refund data. This should be done by sending a new refund to the Swell API via the POST: Create A Refund endpoint outlined below to modify the previously processed order.

Step 4: Enabling loyalty

In order for the cartridge to work you need to enable Loyalty:

1. Navigate to Merchant Tools > Site Preferences > Custom Preferences > Yotpo Configs
2. Enable the Yotpo Loyalty & Referrals settings by updating the Swell Loyalty Enabled field to "Yes"
   

Step 5: Giving Yotpo OCAPI permissions

Yotpo uses OCAPI (Salesforce's Open Commerce API) as part of the loyalty integration. In order to give Yotpo permissions to OCAPI, you need to create a user on Salesforce that has the relevant OCAPI permissions. Then you will provide Yotpo with the user and password in the integration phase (step 7).

Endpoints

Yotpo uses two types of endpoints on OCAPI - Shop and Data. The following endpoints are needed for the Yotpo integration: See here the full documentation on Salesforce. 

Adding the endpoints to Salesforce

In order to give Yotpo permissions for all of the above endpoints, You will need to upload two files to the business manager. One to the shop OCAPI and one to the data OCAPI. Navigate to Administration > Site Development > Open Commerce API SettingsUnder the Shop settings, copy the endpoints from this file.

Under the Data settings, copy the endpoints from this file.

Step 6: Enabling login to Yotpo via Salesforce

In this section, we explain how to add a Yotpo login function to your Salesforce admin. This is important in SFCC to have Yotpo credentials. Permission to access the Loyalty module must be granted to a specific role. 

1. Navigate to the following path: Administration > Organization > Roles & Permissions
2. Select the relevant role to be granted e.g. Administrator
3. Open the Business Manager Module tab as shown below in the animation below.
4. Choose the relevant site
5. Check the box adjacent to Yotpo Swell Login
6. Click Update

Step 7: Yotpo Loyalty & Referrals admin registration

Lastly, complete the integration through the Yotpo Loyalty & Referrals admin dashboard which can be accessed via the Business Manager module:

1. Navigate to Merchant Tools > Site Preferences > Yotpo Swell Login
2. Select the specific locale configured in Yotpo Configurations (custom object). Your Yotpo Loyalty & Referrals GUID and API Key will be automatically populated.
3. Click the Login button to access your Yotpo Loyalty & Referrals admin.
   
4. Within the Loyalty Admin, click Integrations
5. Select Commerce Cloud from the dropdown list of integrations
6. Fill in the fields with the relevant details/ identifiers and click Add Integration when you're done

Registration error

If you see an error message in your Yotpo Loyalty & Referrals admin at the point of registration, follow the instruction below to see how to resolve it and continue with the integration:

Suffix - Data storage

Yotpo uses custom attributes - special fields used to add details to objects. This is an SFCC feature that allows you to add additional info to objects.

This allows us to receive additional information about the shoppers, orders, and redemptions to fully correlate these details within our system to present in our Loyalty dashboards (link)

Below you can see a breakdown of the attributes added as part of the cartridge that we then use to showcase within the boards:

Order custom attributes

PriceAdjustment custom attributes

ProductLineItem custom attributes

OrderPaymentInstrument custom attributes

GiftCertificate Custom Attributes

Configuring order processing flow

The Settings section of your Yotpo Loyalty & Referrals admin allows you to choose an order status that will trigger point deduction and an order status that will trigger the rewarding of points.

• Point deduction

Set a trigger that will deduct the points a shopper used to redeem coupons or discounts when making the purchase. Yotpo will deduct the points as the status is registered in our system. 

We recommend deducting points at the point of order creation to avoid a time gap where shoppers may try to redeem points that are no longer available to them.

• Rewarding points

If you are using a payment processing provider such as WorldPay, the payment approval process for a new order may take some time. Ideally, we do not want to reward a shopper with points before the payment has been approved.

Setting up an order status 'COMPLETED' as the trigger for rewarding points will ensure that points will be given only after the payment has been processed and confirmed.

We recommend setting the trigger post-payment approval so as not to reward customers with points for an unsuccessful purchase.