Setting Up Loyalty & Referrals on SFCC SFRA

      Setting Up Loyalty & Referrals on SFCC SFRA


        Article summary

        Products


        Loyalty
        Supported plans

        Premium, Enterprise

        eCommerce Platform

        Salesforce Commerce Cloud

        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:

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

        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/customerYotpoLoyalty-GetCustomerWhen Yotpo needs specific information on a single customer
        swell/index/customersYotpoLoyalty-GetCustomersWhen a new merchant onboards, Yotpo pulls past customers
        swell/index/orderYotpoLoyalty-GetOrderWhen Yotpo needs specific information on a single order (for processing refunds for example)
        swell/index/ordersYotpoLoyalty-GetOrdersWhen a new merchant onboards, Yotpo pulls past orders
        swell/index/thirty-day-order-volumeYotpoLoyalty-GetOrderCountByVolumeVerifying communication between SFCC and the cartridge
        swell/index/create-gift-certificateYotpoLoyalty-CreateGiftCertificateWhen the merchant uses gift certificates, this endpoint is used
        swell/index/coupon-codeYotpoLoyalty-GetCouponCodeThis 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.

        Navigate to the Yotpo Loyalty & Referrals  Rewards and view the relevant reward:

        Make sure to update the Coupon Code ID with the relevant SFCC coupon ID so that the correct coupon is given to the customer.

        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 NameDescription
        yotpoLoyaltyS2FPromotionSend to Friend Loyalty Discount Promotion
        Campaign NameDescription
        yotpoLoyaltyS2FCampaignSend to Friend Loyalty Discount Campaign
        Coupon NameDescription
        yotpoLoyaltyS2FCouponCoupon 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. 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. 

        EndpointDescription
        /baskets/#{basket_id}/payment_instrumentsAdd 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}/itemsAdd 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_adjustmentsAdd 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}/couponsAutomatically 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 SettingsYou can see the full endpoint list here:

        • For Shop settings, view this file
        • For Data settings, view this file
        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 placeholder “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 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.

        To learn how to find your module instance ID, please click here.

        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:

        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:

        Custom Attribute NameFunction
        Yotpo Cartridge EnabledEnables/disables the Yotpo cartridge
        Yotpo Loyalty EnabledEnables/disables Yotpo Loyalty
        Yotpo Static Content URLThe base URL to load static content from Yotpo
        Yotpo Conversion Tracking Pixel URLConversion tracking pixel URL
        Product Information From MasterMakes production information configurable whether the information will be exported from master or from variants.
        Export Group ID in OrderUsed to make the logic configurable that whether the master product if will be exported as JSON or not.
        Yotpo Orders Batch SizeThis attribute contains batch size for the number of orders that should be processed at one time, while exporting purchase feed.
        Yotpo Loyalty Static Content URLThe URL used to load static content for Yotpo JavaScript
        Yotpo Info Log EnabledThe 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 EnabledThe 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 IDThe 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:

        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
        FieldDescription
        Instance TypeSelect Production or Sandbox environment. Note that each instance must be connected to a different Yotpo Loyalty & Referrals account.
        Client IDSalesforce Client ID
        Client PasswordSalesforce Client Password
        User LoginSalesforce User Login - this user needs to have permission to add price adjustments to a basket.
        User PasswordSalesforce User Password
        HostnameYour 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 IDSalesforce 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 VersionSpecify which Open Cart API version is used in the following format:v19_1The value must match the latest OCAPI version available.
        Cartridge VersionPlease 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:

        ErrorSolution
        Invalid client id, client password, user login, or user passwordThis 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 adminThis 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

        IDNameDescriptionType
        userAgentUser AgentThis attribute stores the user agent information at the time of order placementString
        userIPAddressUser IP AddressThis attribute stores the user IP address information at the time of order placementString

        PriceAdjustment custom attributes

        IDNameDescriptionType
        swellPointsUsedSwell Points UsedThe number of points used as part of the  redemptionInteger
        swellRedemptionIdSwell Redemption IdThe detail required to associate Yotpo's internal redemption ID with the price adjustment happening on siteString

        ProductLineItem custom attributes

        IDNameDescriptionType
        swellPointsUsedSwell Points UsedThe number of points used as part of the  redemptionInteger
        swellRedemptionIdSwell Redemption IdThe detail required to associate Yotpo's internal redemption ID with the price adjustment happening on siteString

        OrderPaymentInstrument custom attributes

        IDNameDescriptionType
        swellPointsUsedSwell Points UsedThe number of points used as part of the  redemptionInteger
        swellRedemptionIdSwell Redemption IdThe detail required to associate Yotpo's internal redemption ID with the price adjustment happening on siteString

        GiftCertificate Custom Attributes

        IDNameDescriptionType
        swellPointsUsedSwell Points UsedThe number of points used as part of the  redemptionInteger
        swellRedemptionIdSwell Redemption IdThe detail required to associate Yotpo's internal redemption ID with the price adjustment happening on siteString

        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?