Setting Up Loyalty & Referrals on SFCC SFRA
Setting Up Loyalty & Referrals on SFCC SFRA
Article Summary
Share feedback
Thanks for sharing your feedback!
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.
Which article do I need?
This article covers the installation process of the Yotpo Loyalty & Referrals Cartridge for Salesforce Commerce Cloud's SFRA version.
For instructions on how to install the Yotpo Loyalty & Referrals Cartridge on Salesforce Controllers and Pipelines, please see this article.
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
- In order to use the Salesforce Commerce Link Cartridge, you must be subscribed to an eligible Yotpo premium plan.
- Use of the Yotpo LINK cartridge by itself does not grant nor enable the use of Yotpo product offerings. You must first enter a contractual agreement with Yotpo in order for Yotpo's loyalty and referral program to run.
- To learn more, please reach out to Yotpo Sales at: sales@yotpo.com
Cartridge overview
Important:
The Yotpo LINK cartridge is compatible with StoreFront Reference Architecture (SFRA) version 4.2.1 or later and Salesforce Commerce Cloud (SFCC) compatibility mode 17.7or later.
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:
- Navigate to the Metadata > SiteImport > Sites folder in the Yotpo LINK Cartridge
- Change the name of the folder “RefArch” to the site ID of your site
- Use a compression tool to create a .zip of the SiteImport folder
- 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:
- Navigate to Site Development > Site Import & Export
- 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.
Additional information on the services setup can be found in the expandable arrows below or download the integration guide in PDF format.
Yotpo Jobs Details
Important!
A basic configuration for these jobs is included in the metadata import.
However, the default site for the jobs is “RefArch” - The correct sites must be configured. This configuration is located under the “Scope” section inside of the “Job Steps” tab.
However, the default site for the jobs is “RefArch” - The correct sites must be configured. This configuration is located under the “Scope” section inside of the “Job Steps” tab.
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:
| Alias (URL in BM) | Pipeline (Method in Yotpo's Cartridge) | Why is this needed |
|---|---|---|
| swell/index/customer | YotpoLoyalty-GetCustomer | When Yotpo needs specific information on a single customer |
| swell/index/customers | YotpoLoyalty-GetCustomers | When a new merchant onboards, Yotpo pulls past customers |
| swell/index/order | YotpoLoyalty-GetOrder | When Yotpo needs specific information on a single order (for processing refunds for example) |
| swell/index/orders | YotpoLoyalty-GetOrders | When a new merchant onboards, Yotpo pulls past orders |
| swell/index/thirty-day-order-volume | YotpoLoyalty-GetOrderCountByVolume | Verifying communication between SFCC and the cartridge |
| swell/index/create-gift-certificate | YotpoLoyalty-CreateGiftCertificate | When the merchant uses gift certificates, this endpoint is used |
| swell/index/coupon-code | YotpoLoyalty-GetCouponCode | This endpoint retrieves a coupon code from the SFCC platform to provide to your shoppers |
The settings will look like this
Please Note:
These endpoints are consumed by the Yotpo server during the setup of the Commerce Cloud integration through the Yotpo Loyalty Admin.
Please verify these mappings are set correctly after completing the site import.
Referral Promotion, Campaign, and Coupon
Important!
To ensure that the referral coupon is properly awarded from the automatically created coupon, it is required to input the Coupon Code ID of the coupon into the relevant coupon setting in the Yotpo Loyalty & Referrals Admin.
Additional information can be found here.
Additional information can be found here.
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.
| Promotion Name | Description |
|---|---|
| yotpoLoyaltyS2FPromotion | Send to Friend Loyalty Discount Promotion |
| Campaign Name | Description |
|---|---|
| yotpoLoyaltyS2FCampaign | Send to Friend Loyalty Discount Campaign |
| Coupon Name | Description |
|---|---|
| yotpoLoyaltyS2FCoupon | Coupon sent via Yotpo Loyalty when a user opts to send it to a friend |
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. 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 step. The metadata import will automatically add the following Open Commerce API (OCAPI) settings to Administration > Site Development > Open Commerce API Settings.
Important!
The user login and password credentials have to be that of an actual user (meaning, can be used to log into the SFCC Business Manager).
These credentials expire every 90 days. The loyalty/integrations/integration_disabled event will be sent to the webhook URL and the integration will be disabled.
You will have to update the new password in the Loyalty & Referrals admin to ensure that Yotpo is able to access your SFCC store to generate rewards, as well as retrieve customers and orders.
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.
| Endpoint | Description |
|---|---|
| /baskets/#{basket_id}/payment_instruments | Add payment instrument to basket. When the customer redeems points for a gift certificate and applies it to the basket - this endpoint is used. |
| /baskets/#{basket_id}/payment_instruments/#{payment_instrument_id} | Remove Payment instrument from basket. When the customer removes a gift certificate from the basket, this endpoint is used. |
| /baskets/#{basket_id}/items | Add product to basket. When there is a free product redemption (customers redeems points for product), this endpoint is used to add the product to the basket. |
| /baskets/#{basket_id}/items/#{item_id} | Remove product from basket. If the customer decided they do not want the free product, this endpoint is used to remove the product from the basket. |
| /baskets/#{basket_id}/price_adjustments | Add price adjustment to basket. When using fixed amount/ percentage/ variable redemption, this endpoint is used in order to give the discount to the customer. |
| /baskets/#{basket_id}/price_adjustments/#{price_adjustment_id} | Remove price adjustment from basket. If the customer decided to remove the discount from the basket, this endpoint is used to remove it. |
| /baskets/#{basket_id} | Get information on basket. Used to understand which redemptions are part of the basket in order to know how many points to present to the customer. |
| /baskets/ /baskets/#{basket_id}/storefront | Create basket. Mainly used for free product redemptions, when there is no basket and the customer redeemed a product, we create the basket for the customer. |
| /baskets/#{basket_id}/coupons | Automatically add coupon to basket. Used for the referred friend coupon to auto apply it to the basket. |
You can see all the relevant OCAPI permission by navigating to Administration > Site Development > Open Commerce API Settings
You can see the full endpoint list here:
Please Note:
A basic configuration for these OCAPI settings is included in the metadata import.
However, the default client ID for the settings is the place holder “aaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.” The correct client ID must be configured.
This configuration is located under the “client_id” section inside of the “Open Commerce API Settings” and must be set to the appropriate client ID for both the “Shop” and “Data” dropdown selections.
We recommend changing the default Client ID from its default setting. This also applies to staging/dev accounts.
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”
Overrides:
If any of these templates are also overwritten by another cartridge, you will have to merge the changes from that cartridge with the changes made in the Yotpo version of the template.
The recommended approach is to create a separate cartridge that contains only the merged templates.
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 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 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.
POST: https://loyalty.yotpo.com/commerce-cloud/refunds
This endpoint records a refund made by you for an existing order. It will apply the refund to the order and then adjust any reward given by the original order.
Please see the API specifications and parameters here.
Step 4: Enable Loyalty on SFCC
In order for the cartridge to work you need to enable Yotpo:
- Navigate to Merchant Tools > Site Preferences > Custom Preferences > Yotpo Configs
- Enable the Yotpo Cartridge by setting the Yotpo Cartridge Enabled setting to "Yes"
- Enable the Loyalty features of the cartridge by setting the Yotpo Loyalty Enabled to "Yes"
Additional attributes:
| Custom Attribute Name | Function |
|---|---|
| Yotpo Cartridge Enabled | Enables/disables the Yotpo cartridge |
| Yotpo Loyalty Enabled | Enables/disables Yotpo Loyalty |
| Yotpo Static Content URL | The base URL to load static content from Yotpo |
| Yotpo Conversion Tracking Pixel URL | Conversion tracking pixel URL |
| Product Information From Master | Makes production information configurable whether the information will be exported from master or from variants. |
| Export Group ID in Order | Used to make the logic configurable that whether the master product if will be exported as JSON or not. |
| Yotpo Orders Batch Size | This attribute contains batch size for the number of orders that should be processed at one time, while exporting purchase feed. |
| Yotpo Loyalty Static Content URL | The URL used to load static content for Yotpo JavaScript |
| Yotpo Info Log Enabled | The flag controls the info log level in whole Yotpo cartridge. By default, the info log will be disabled, therefore to enable the checkbox should be checked. |
| Yotpo Debug Log Enabled | The flag controls the debug log level in whole Yotpo cartridge. By default, the debug log will be disabled, therefore to enable the checkbox should be checked. |
| Yotpo Loyalty API Key | Provide the Yotpo loyalty API Key |
| Yotpo Loyalty GUID | Provide the Yotpo loyalty GUID |
| Yotpo Loyalty Order Feed Enabled | Enable sending order information to Yotpo Loyalty. Set to "Yes" by default. |
| Yotpo Loyalty Customer Feed Enabled | Enable sending customer information to Yotpo Loyalty. Set to "Yes" by default. |
| Yotpo Loyalty Checkout Module Instance ID | The instance ID of the redemption widget to be included as part of the checkout. |
Step 5: Yotpo Loyalty & Referrals Admin Registration
Lastly, complete the integration through the Yotpo Loyalty & Referrals Admin:
- Retrieve your Yotpo Loyalty & Referrals API Key and GUID from your Yotpo Loyalty & Referrals Admin, as described here.
- Navigate to Merchant Tools > Site Preferences > Custom Preferences > Yotpo Configs
- Update the Yotpo Loyalty API Key and Yotpo Loyalty GUID elements with your specific keys.
- Back in the Yotpo Loyalty & Referrals Admin, click Integrations
- Select Commerce Cloud from the dropdown list of integrations
- Fill in the fields with the relevant details/ identifiers and click Add Integrationwhen you're done
- Note: Upon clicking Add Integration for the first time, all historical order and customer data will be retrieved.
- Make sure to set the Cartridge Version to V2 to ensure all of the features are available for use within the Loyalty & Referrals Admin
- Note: Upon clicking Add Integration for the first time, all historical order and customer data will be retrieved.
| Field | Description |
|---|---|
| Instance Type | Select Production or Sandbox environment. Note that each instance must be connected to a different Yotpo Loyalty & Referrals account. |
| Client ID | Salesforce Client ID |
| Client Password | Salesforce Client Password |
| User Login | Salesforce User Login - this user needs to have permission to add price adjustments to a basket. |
| User Password | Salesforce User Password |
| Hostname | Your store's URL e.g. https://amizingstore.com You may choose to temporarily protect your site with a user name and password. You can add those details to the Yotpo Loyalty admin so that Yotpo can have access to your protected site. Simply add the storefront credentials to the Salesforce integration page in your Yotpo Loyalty admin in the following format: If the storefront URL is: https://yotpo03-tech-prtnr-eu03-dw.demandware.net/and the storefront credentials are as follow: user_name: userpassword: strong_password then the Hostname value should be added like this: https://user:strong_password@yotpo03-tech-prtnr-eu03-dw.demandware.net/ |
| Site ID | Salesforce Site ID. The Site Id can be found in your SFCC admin under Administration > Sites > Manage Sites Note: If you have implemented any URL redirections after the initial locale, make sure to add them to this field as part of the integration. |
| OCAPI Version | Specify which Open Cart API version is used in the following format:v19_1The value must match the latest OCAPI version available. |
| Cartridge Version | Please select V2 to ensure that you are seeing all of the relevant features for this integration |
Important!
The user login and password credentials have to be that of an actual user (meaning, can be used to log into the SFCC Business Manager).
These credentials expire every 90 days. The loyalty/integrations/integration_disabled event will be sent to the webhook URL and the integration will be disabled.
You will have to update the new password in the Loyalty & Referrals admin to ensure that Yotpo is able to access your SFCC store to generate rewards, as well as retrieve customers and orders.
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:
| Error | Solution |
|---|---|
Invalid client id, client password, user login, or user password | This means that the OCAPI credentials are invalid. You can review this section of the process here. |
Either one of these fields is wrong (Hostname, Site ID, OCAPI Version) or Cartridge configured incorrectly in Commerce Cloud admin | This means that the URL mapping may not have been added correctly. You can review this section of the process here. |
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
| ID | Name | Description | Type |
|---|---|---|---|
| userAgent | User Agent | This attribute stores the user agent information at the time of order placement | String |
| userIPAddress | User IP Address | This attribute stores the user IP address information at the time of order placement | String |
PriceAdjustment custom attributes
| ID | Name | Description | Type |
|---|---|---|---|
| swellPointsUsed | Swell Points Used | The number of points used as part of the redemption | Integer |
| swellRedemptionId | Swell Redemption Id | The detail required to associate Yotpo's internal redemption ID with the price adjustment happening on site | String |
ProductLineItem custom attributes
| ID | Name | Description | Type |
|---|---|---|---|
| swellPointsUsed | Swell Points Used | The number of points used as part of the redemption | Integer |
| swellRedemptionId | Swell Redemption Id | The detail required to associate Yotpo's internal redemption ID with the price adjustment happening on site | String |
OrderPaymentInstrument custom attributes
| ID | Name | Description | Type |
|---|---|---|---|
| swellPointsUsed | Swell Points Used | The number of points used as part of the redemption | Integer |
| swellRedemptionId | Swell Redemption Id | The detail required to associate Yotpo's internal redemption ID with the price adjustment happening on site | String |
GiftCertificate Custom Attributes
| ID | Name | Description | Type |
|---|---|---|---|
| swellPointsUsed | Swell Points Used | The number of points used as part of the redemption | Integer |
| swellRedemptionId | Swell Redemption Id | The detail required to associate Yotpo's internal redemption ID with the price adjustment happening on site | String |
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.
Was this article helpful?
