Implementing Loyalty & Referrals on a Custom or Generic eCommerce Platform
Implementing Loyalty & Referrals on a Custom or Generic eCommerce Platform
Article Summary
Share feedback
Thanks for sharing your feedback!
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:
- Backend setup - Connecting your eCommerce platform with Yotpo and making sure there’s a constant flow of information between the two.
- Admin configuration - Configuring account details within your Loyalty & Referrals admin.
- Coupons types: custom coupons vs. dynamic redemption - Deciding which type of coupons works best for you and implementing the selected method
- 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
- Tags - To limit campaigns to specific customer tags.
- Has_account - This will complete the Create an Account campaign if the shopper has created an account with your store and the campaign is set up in the admin. The parameter will also opt-in a customer if the opt-in strategy is set to Platform Account.
- Opted_in - Will opt-in a customer regardless of the strategy chosen in your Yotpo Loyalty & Referrals admin.
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 before 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 Coupons | Dynamic Redemption |
|---|---|
| Delayed point deduction is not available | Delayed point deduction available |
| Does not require dev resources | Requires dev resources |
| Must be manually maintained. You can automate the process with minimal dev resources. Learn more | An automatic process that must be set up by the merchant |
| Requires you to create coupon codes in bulk | Requires 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” coupons | Supports 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:
- 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>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 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:
- The signature is a hexadecimal digest using SHA256.
- The message input of the SHA256 should be a sorted concatenation of the following values:
- Customer email.
- 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
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
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:
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?
