Implementing Loyalty & Referrals on a Custom or Generic eCommerce Platform

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

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:

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.

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:

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.

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

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: 

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:

• Their email address 
• The third-party ID sent to Yotpo via the Create/Update Customer or Create Order API endpoints

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

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

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.

SHA256 Signature example:

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

On-site 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:

• Rewards page builder
• Refer Friends module
• Product Share Referral module
• Referral Welcome popup
• My Activity module
• Earning Points module
• Redeem Points modules
• VIP Tiers module

Advanced modules

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:

• Checkout for generic integration
• Free product for generic integration

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.