Implementing Loyalty & Referrals on a Custom or Generic eCommerce Platform

      Implementing Loyalty & Referrals on a Custom or Generic eCommerce Platform


        Article Summary

        Products


        Loyalty
        Supported plans

        Free, Gold, Platinum, Enterprise

        eCommerce Platform

        Custom

        This guide provides a comprehensive overview of how to implement Yotpo Loyalty and Referrals on a generic non-hosted or custom-built eCommerce store.
        The integration consists of four main aspects:

        1. Backend setup - Connecting your eCommerce platform with Yotpo and making sure there’s a constant flow of information between the two.
        2. Admin configuration - Configuring account details within your Loyalty & Referrals admin.
        3. Coupons types: custom coupons vs. dynamic redemption - Deciding which type of coupons works best for you and implementing the selected method
        4. Frontend elements - Adding Yotpo Loyalty & Referrals elements to your store so that shoppers can interact with your rewards and referral programs.

        Backend setup

        Log in to your account or create a new one by clicking here

        Order data

        Use the Create order API endpoint to send your store’s order data to Yotpo. Below are some specific parameters to pay attention to:

        customer_id

        This is the customer identifier in your eCommerce platform. It will be used to connect the loyalty user with the platform user. This parameter allows Yotpo to authenticate the user profile and only lets confirmed users use their points for discounts in your store.

        Additionally, if a user changes their email address, the customer_id parameter will be used to update the customer details on Yotpo's end without losing all the relevant loyalty and referral data.

        total_amount_cents

        This parameter allows you to send the order amount so Yotpo's system will be able to grant rewards accordingly. 

        Please make sure to:

        • Exclude discounts from the final amount sent to Yotpo
        • If you wish to exclude/include shipping & taxes when running the Points for Purchase campaign, send the relevant order amount before/after shipping & taxes. Simply choose the sum you’d like to reward the shopper for. 

        Make sure this information is also reflected in the refund data sent to Yotpo.

        status

        This is the order status. Yotpo uses this parameter to determine whether points should be added or deducted from the shopper. Note: This is only relevant to merchants using delayed point deduction with dynamic redemption coupons.

        The different order statuses that trigger these changes must be configured in the Settings section of your L&R admin:

        • Order paid status - The trigger for deducting delayed point deduction redemptions
        • Process order with status - The trigger for processing an order and giving rewards

        If no status is configured in the admin, our system will process both the discount and the order as soon as we receive the order information via an API call.

        If two different statuses are configured - If you configured a different status for each field, you will need to run the API call twice so Yotpo will be able to register the order status change and perform the relevant action.

        We recommend rewarding points only once the order is shipped or completed to prevent customers from using points prematurely.

        created_at

        The time when the order was created. If the parameter isn’t included, we will use the data intake time as the created_at parameter. This is mostly relevant when rewarding customers for completing a scheduled campaign within the relevant time frame.

        coupon_code

        Coupon codes used by the shopper when creating the order should be included in the order data. Only Yotpo Loyalty & Referrals related codes will be saved in the system. 

        Associating the codes with orders is how our system recognizes redeeming customers across the loyalty and referrals dashboards.

        ignore_ip_ua

        If set to 'true', Yotpo will ignore the ip_address and user_agent fraud checks, allowing a referral to be completed even if no ip_address or user_agent are provided. 

        If these parameters are provided while set to 'true', the fraud checks will be ignored. 

        If you wish to use this feature, please reach out to your Yotpo representative or our support team in order to enable it.

        discount_amount_cents

        The discount amount that was applied to the order.

        tags

        These are order tags. They can be used to limit spend-based campaigns - Points for Purchases, Punch Card and Goal Spend, to specific orders.

        customer_object

        Refund data

        When orders are changed and refunds are made, you'll need to use the Create Refund API endpoint

        This will trigger:

        • A deduction of points that were earned prior to the refund
        • Re-allocation of points used for a discount on the order or a returned product

        One parameter to pay is the Items parameter - if you’re using the Required Product IDs/Exclude Specific Product Types settings in your campaigns, It’s important you send information about items that were refunded:

        For example, a Points for Purchase campaign that runs only for a specific product - our system needs to be aware that this product was refunded, resulting in the points awarded for purchasing it reverted.

        Please note:
        If shipping & taxes were included in the original order sum sent to Yotpo, make sure they are also reflected in the refund data.

        Customer data

        Use the Create/Update Customer Records API endpoint to send your store’s order data to Yotpo. Below are some specific parameters to pay attention to:

        id

        This is the customer identifier in your eCommerce platform. It will be used to connect the loyalty user with the platform user.This parameter allows Yotpo to authenticate the user profile and only lets confirmed users use their points for discounts.

        Additionally, if a user changes their email address, the customer_id parameter will be used to update the customer details on Yotpo's end without losing all the relevant loyalty and referral data.

        has_account

        This parameter lets Yotpo know whether the customer has an account with the platform. 

        By default, it is set to False. Marking the value as "True" will complete the Create an Account campaign if one is set up. It will also impact the customer’s opt-in status if the opt-in strategy is set to “Platform Account”.

        opted_in/opted_in_at

        This parameter determines the customer’s opt-in status. If it’s not included, we will rely on the opt-in strategy set up in your loyalty account.

        tags

        Customer tags are relevant for targeting customers on specific campaigns. You can use the tags to include or exclude customers from desired campaigns:

        Admin configuration

        The step requires some modifications to be implemented within your Yotpo Loyalty & Referrals admin.

        Admin settings

        • Account registration URL - Relevant for on-site elements so that if users wish to create an account, the button in the element will take them to the correct account creation URL.
        • Sign up URL - Relevant for on-site elements so that if users wish to sign up, the button in the element will take them to the correct signup URL.

        Important:

        Please make sure to set these up prior to setting up the modules. If the URL changes or was set after module creation, please contact support to update the existing modules. 

        Do not duplicate modules as this setting will also be automatically duplicated.

        • Process order with status -  The order status that will trigger the processing of an order and the addition of points or rewards.
        • Order paid status - The order status that will trigger delayed point deduction redemptions.
        Please note:
        • If no status is configured in the admin, our system will process both the discount and the order as soon as we receive the order information via an API call.
        • If two different statuses are configured - If you configured a different status for each field, you will need to run the API call twice so Yotpo will be able to register the order status change and perform the relevant action.

        We recommend rewarding points only once the order is shipped or completed to prevent customers from using points prematurely.

        Coupons types: custom coupons vs. dynamic redemption

        Since Yotpo is not fully integrated with your eCommerce platform, coupon codes generated in your platform must be actively shared with Yotpo. 

        There are two ways in which you can send Yotpo coupon codes shared with the shopper: 

        Custom CouponsDynamic Redemption
        Delayed point deduction is not availableDelayed point deduction available
        Does not require dev resourcesRequires dev resources
        Must be manually maintained. You can automate the process with minimal dev resources. Learn moreAn automatic process that must be set up by the merchant
        Requires you to create coupon codes in bulkRequires the platform to be able to generate coupons on demand
        Multi-currency can only be supported by using “Percentage off” coupons and not “Fixed amount” couponsSupports Multi-currency feature

        Settings up custom coupons

        In your platform, you'll need to create bulk coupon codes for each type of reward you wish to offer. For example, if you want to offer $5 Off, $10 Off, and $25 Off coupons, you'll need to make sure to create bulk coupon codes for each one of these reward options. 

        Follow the steps in this article to create the different coupon options in your Yotpo Loyalty & Referrals admin, and possibly even set up an automated flow to continuously upload codes via API.

        Setting up dynamic redemption

        Dynamic redemption allows Yotpo to reach out to an API endpoint of your choice and request the creation of a coupon code on the fly. This way, coupon codes can be created on-demand instead of uploaded in bulk into the Loyalty admin.

        To set up dynamic redemption, follow the steps in this article.

        Frontend elements

        Secure customer identification

        Yotpo’s on-site elements must have a way of recognizing who is completing actions on your storefront. It's necessary to identify the user currently logged-in and show them the discounts and point balances relevant to them.

        Customers can be identified by:

        For our on-site elements to be able to identify the customer and show them the details relevant to their account, you’ll need to implement a hidden <div> tag with a signature token in your layout. This div must be present on the page before Yotpo’s JavaScript runs so that the on-site elements will show the information relevant to that shopper (i.e. their point balance, completed campaigns, etc).

        On page load, the Loyalty & Referrals JS SDK/modules will scan the DOM of the following element:

        <div
        id="swell-customer-identification"
        data-authenticated="true"
        data-email="##customer-email##"
        data-id="##customer-id##"
        data-token="##customer-token##"
        data-tags="##customer-tags##"
        style="display:none;">
        </div>

        Example:

        <div
        id="swell-customer-identification"
        data-authenticated="true"
        data-email="johnsmith@exmaple.com"
        data-id="12345"
        data-token="e490e002595788b184a23cea19dbe158c1f038886643de476648735ba3fd0779"
        data-tags="[“VIP”,“wholesale”]"
        style="display:none;">
        </div>
        Please note:
        The data-tags attribute should be a JSON string representing an array of string tags. For example, if the customer was tagged “VIP” and “wholesale” you’ll need the tags to look like this: data-tags=‘[“VIP”,“wholesale”]’

        If the customer identification token is confirmed, the JS SDK/modules will populate with details relevant to that customer: point balance, VIP tier status, campaign completions, etc.

        Important:
        This <div> must be located on every page that has Yotpo Loyalty & Referrals on-site elements. 

        Creating a token

        To verify the integrity of the data shown to the customer and to ensure their identity, we enforce attaching a digested hash signature token. This token is injected by you onto the page and cannot be generated or copied by an attacker.

        Use the SHA256 hash type signature:

        1. The signature is a hexadecimal digest using SHA256.
        2. The message input of the SHA256 should be a sorted concatenation of the following values:
          1. Customer email.
          2. Your Yotpo Loyalty & Referrals API Key. Make sure that your API key is not exposed at any point or leaked to any individual.
        Tip:

        You can generate an example signature using the SHA256 Generator.

        SHA256 Signature example:

        • Customer email: johnsmith@example.com
        • Your Yotpo loyalty and Referrals API Key: 8GpA6t3jvGW8fHmvQNeLYf0EEz6CjFmzJFOTOn4y


        Modules and JS SDK

        When adding on-site loyalty elements, you can choose to go with one of the following options:

        Modules

        Modules are easy-to-use widgets that can be configured and edited from within your Yotpo admin. Once you finish configuring a module, you’ll get a code snippet that you can add to the desired page within your store. Any additional changes you make to the module will immediately reflect on-site after the code has been added.

        Interactions with the modules are also recorded and displayed across the various loyalty dashboards and provide insight into your user activity and program ROI.

        Click on the module to learn how to set it up:

        Advanced modules

        Please note:
        The following modules will require advanced dev resources

        For a smoother customer experience where the shopper doesn't need to copy-paste a coupon code to receive a discount or free product, implement the following modules:

        JS SDK

        You can create your own on-site loyalty elements by using our Javascript SDK. 

        Yotpo triggers events on the document object enabling you to hook into key interactions your customers are taking with the program.

        To see the full list of available interactions, view our SDK documentation. You can also use our SDK functionality guides to get you started.

        The following snippet should be added as it appears below with your Loyalty & Referrals JS SDK inserted in the src=

        <html>
            <head>
                <!-- rest of your js/css includes -->
                <script type="text/javascript" async src="https://cdn-loyalty.yotpo.com/loader/<YOUR GUID GOES HERE>.js"></script>
            </head>
            <body>
                
            </body>
        </html> 
        Please note:
        Implementing Javascript SDK requires extensive dev resources. Additionally, referral flows and user behavior can only be monitored via the modules. This means that the referral dashboards will not populate with data if you choose to implement an SDK element.

        Additional features: Multi-currency

        Our multi-currency feature allows shoppers to fully experience your shop and loyalty program in their local or preferred currency.


        To learn more on how to set it up, check out our Multi-Currency Loyalty & Referrals Setup on a Custom or Generic eCommerce Platform article.


        Was this article helpful?