Setting Up Loyalty & Referrals on SFCC SFRA

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 V2 Salesforce Commerce Link Cartridge - enabling you to integrate various Yotpo features within an SFRA Salesforce Commerce store.

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 int_yotpo_sfra cartridge. 

Terms of service

In using the Yotpo LINK cartridge, you agree to Yotpo's Terms of Service.

Step 1: Configuration

Cartridge registration

Navigate to the following path:Sites > Manage Sites > Merchant Site > Settings

Add the cartridge int_yotpo_sfra within the Cartridges field as shown below:

Add Yotpo LINK Cartridge to Code Base

The Yotpo LINK Cartridge code must be added to your codebase and uploaded to the appropriate Salesforce Commerce Cloud instance prior to site and metadata import.

Import Yotpo's Site Import

The Yotpo cartridge includes a SiteImport file in the cartridge’s Metadata folder. The configurations in this folder are set up to work sites that have a site ID of ‘RefArch.’

Prior to importing, you will need to modify the site-specific folder included in the SiteImport to replace references to ‘RefArch’ with the site ID of your site:

1. Navigate to the Metadata > SiteImport > Sites folder in the Yotpo LINK Cartridge
2. Change the name of the folder “RefArch” to the site ID of your site
3. Use a compression tool to create a .zip of the SiteImport folder
4. Navigate to Site Development > Site Import & Export, select the SitesImport.zip file you just created and click on ‘Import’ to complete the import process through the interface

Import Yotpo Metadata, Services, and Jobs Schedules

The Yotpo cartridge also includes a metadata.zip import file in the cartridge’s Metadata folder.

To import the file:

1. Navigate to Site Development > Site Import & Export
2. Select metadata.zip file and click on ‘Import’ to complete the import process through the interface

Once the file is upload, click the Import button next to "Meta data". You'll be guided through a Salesforce Commerce Cloud installation wizard.The Jobs, Services, Site Preferences, and Custom Objects will be imported (including Yotpo Configurations and Yotpo Jobs Configurations) and will automatically be populated with the following settings and attributes.

Yotpo Jobs Details

Services details

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

To view the details, navigate to Administration > Operations > Services > Click on the Credentials tab.

• In the Name field, you will see the following: int_yotpo.sfra.http.post.loyalty.api.cred
• In the URL field, you will automatically have https://loylaty.yotpo.com/commerce-cloud/

Yotpo Site Preferences Details

 

Yotpo Custom Object Details

 

URL Mappings

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. The site import will automatically add the needed mapping URLs in Pipeline URLs.

The following URLs should be automatically set up in Merchant Tools > SEO > URL Rules > Pipeline URLs:

The settings will look like this

Referral Promotion, Campaign, and Coupon

The site import will automatically add the promotion, campaign, and coupon configurations that allow Yotpo Loyalty to provide a user with a coupon code when a referred friend clicks on a referral link.

The default setup included in the site import gives a user 10% off of their order when a valid yotpoLoyaltyS2FCoupon coupon code is applied.

The “Yotpo Loyalty S2F Promotion” promotion type, discount, and exclusivity may be modified to provide the desired discount for the Loyalty send-to-friend experience.

The site import will generate 10,000 coupon codes for the “yotpoLoyaltyS2FCoupon.” Additional codes may be added as needed.

Promotions, campaigns, and coupons may be accessed through Business Manager by navigating to Merchant Tools > Online Marketing.

Open Commerce API Settings

Yotpo uses OCAPI (Salesforce's Open Commerce API) as part of the loyalty integration. 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 step. The metadata import will automatically add the following Open Commerce API (OCAPI) settings to Administration > Site Development > Open Commerce API Settings.

Endpoints

Yotpo automatically adds and 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. 

You can see all the relevant OCAPI permission by navigating to Administration > Site Development > Open Commerce API SettingsYou can see the full endpoint list here:

• For Shop settings, view this file. 
• For Data settings, view this file. 

Step 2: Template Overrides

The following SFRA templates are overridden as a part of the int_yotpo_sfra cartridge:

“/int_yotpo_sfra/cartridge/templates/default/account/dashboardProfileCards.isml” “/int_yotpo_sfra/cartridge/templates/default/checkout/checkout.isml” “/int_yotpo_sfra/cartridge/templates/default/components/footer/pageFooter.isml”

Automatic Overrides

The JavaScript and the Logged-in Customer and Basket Tracking will automatically be created and overridden as part of the cartridge installation. Additional information can be found here under sections 3.8.3 and 3.8.6.

It will look like this:

Logged in customer and basket tracking

Yotpo needs to get all orders and customers 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 controllers described below:

Order observer

The order observer hook will be added to PlaceOrder (checkout summary submit) controller after order creation with the following code snippet:

Customer observer

The customer observer hook will be added to Account-SubmitRegistration and Account-SaveProfile controllers using the following code snippet:

• Account-SubmitRegistration snippet
  
• Account-SaveProfile snippet
  

Adding On-site Modules

As can be seen here, the Yotpo Loyalty & Referrals product offers a variety of different On-site Modules.

To include custom module injection, the yotpoLoyaltyStaticContentURL custom site preference must be populated and the desired templates must be overridden to include the appropriate widget tag code snippet from Yotpo.

Checkout Module

The LINK cartridge includes a default overridden checkout template (checkout.isml) and affiliated custom site preference (yotpoLoyaltyCheckoutInstanceID). 

The checkout module must be configured and published in the Yotpo Loyalty Admin. Make note of your module instance ID when you publish the module.

Update the yotpoLoyaltyCheckoutInstanceID custom site preference with your specific module instance ID.

The Checkout Module is automatically injected using the default template overrides. Additional information can be found here under section 3.8.8.1.

Additional Yotpo Loyalty Modules

To enable any Yotpo Loyalty module configured and published via the Yotpo Loyalty Admin, with the exception of the Checkout Module, override the desired templates and include the widget tag code snippet from Yotpo.

For example:

<div class="yotpo-widget-instance" data-yotpo-instance-id="1234"/></div>

Step 3: Set Up Refunds

In order to adjust the points earned from refunded orders, as well as 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 Yotpo Loyalty & Referrals API via the POST: Create A Refund endpoint to modify the previously processed order. 

Step 4: Enable Loyalty on SFCC

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

1. Navigate to Merchant Tools > Site Preferences > Custom Preferences > Yotpo Configs 
2. Enable the Yotpo Cartridge by setting the Yotpo Cartridge Enabled setting to "Yes"
3. Enable the Loyalty features of the cartridge by setting the Yotpo Loyalty Enabled to "Yes"
   

Additional attributes:

Step 5: Yotpo Loyalty & Referrals Admin Registration

Lastly, complete the integration through the Yotpo Loyalty & Referrals Admin:

1. Retrieve your Yotpo Loyalty & Referrals API Key and GUID from your Yotpo Loyalty & Referrals Admin, as described here.
2. Navigate to Merchant Tools > Site Preferences > Custom Preferences > Yotpo Configs
3. Update the Yotpo Loyalty API Key and Yotpo Loyalty GUID elements with your specific keys.
4. Back in the Yotpo Loyalty & Referrals 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.

1. Note: Upon clicking Add Integration for the first time, all historical order and customer data will be retrieved.
2. Make sure to set the Cartridge Version to V2 to ensure all of the features are available for use within the Loyalty & Referrals Admin

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's 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 redeemed 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.