Introduction
The Rivo Developer Toolkit empowers developers to customize and extend the Rivo loyalty program according to their specific needs. This guide provides an overview of the key components available within the toolkit:
Metafields: Metafields provide a way to use and display data related to customers and your loyalty program. They can be used within Shopify theme templates and custom blocks to dynamically display loyalty-related information.
RivoJS API: This JavaScript API is designed for client-side usage within your Shopify storefront. It allows you to access and display loyalty data, such as points balances and VIP tiers, directly on your site, as well as perform key actions like redeeming rewards and updating customer birthdays.
REST API: The REST API allows for server-side integration, enabling you to manage and interact with your loyalty program by retrieving and updating customer data, managing rewards, and tracking referrals. It’s ideal for backend processes and third-party integrations.
How do I enable the Developer Toolkit?
✨ You must be on the Plus plan to access the Developer Toolkit
From your Rivo dashboard, go to Settings > Developer Toolkit. You'll see 3 sections:
REST API Keys - Here you can generate your API key for REST API authorization.
Rivo Javascript API - Toggle this on to include the Rivo Javascript API on the storefront.
Rivo Shopify Metafields - Toggle this switch to enable Rivo metafields (customer metafields can take some time to sync, depending on the customer count.)
Metafields
What can I do with them?
Use metafields to dynamically display and leverage data about the logged-in customer and your shop’s loyalty program settings.
We have two metafields, one for shop data and one for customer data:
shop.metafields.rivo.loy
customer.metafields.custom.rivo.value
Where can I use them?
Metafields can be used in Shopify theme templates and custom blocks within the theme customizer, provided those blocks support Liquid. However, they cannot be used in static HTML files outside of these contexts. Ensure you're placing them in areas that allow Liquid code execution.
Example usage
<div>You have {{ customer.metafields.custom.rivo.value.points_balance }} points</div>
<!-- Using the customer object to output their points balance -->
Output:
You have 110 points
<ul> {% for way_to_earn in shop.metafields.rivo.loy.points_program.ways_to_earn %} <li>{{ way_to_earn.title }} for {{ way_to_earn.points_amount }} points</li> {% endfor %} </ul>
<!-- Using the shop object to loop through and display each way to earn and the points earned for each -->
Output:
Sign up for 100 points
Place an order for 1 point
Follow on TikTok for 75 points
RivoJS API
What can I do with it?
The Rivo Javascript API allows you to access data related to the logged-in customer and loyalty program settings. You can retrieve important customer data, such as points logs, referral stats, points balance and VIP tier progress, and leverage it directly on your storefront. Additionally, the API allows you to perform two key actions: redeem rewards and update customer birthdays.
Where can I use it?
The RivoJS API can be utilized in almost any part of your Shopify storefront where JavaScript is supported. It’s added to your store through our theme app extensions, which means certain areas like the checkout and the new customer account page are not supported.
Key Functions:
Retrieve Loyalty Data: Access detailed information about the loyalty program and customer-specific data, including points balance, shop rewards, VIP program etc.
Redeem Rewards: Redeem a reward for a logged-in customer.
Update Customer Birthday: Update a logged-in customer's date of birth for the 'Celebrate a birthday' way to earn.
Example usage
Here's an example of how you might use the RivoJS API to inform a customer how many more points they need to reach the next VIP tier:
<p id="vip-unlock"></p>
<script type="text/javascript">
document.addEventListener("rivo-js-loaded", function() {
RivoJS.getCustomerVipTier().then(function(resp) {
var pointsNeeded = resp.next_tier.to_spend_or_earn;
var tierName = resp.next_tier.name;
var vipInfoP = document.getElementById('vip-unlock');
if (vipInfoP) {
vipInfoP.innerHTML = "Earn " + pointsNeeded + " more points to reach " + tierName;
}
});
});
</script>
<!-- listen for the rivo-js-loaded event, ensuring the API is ready before attempting to fetch the customer’s VIP tier data. Then, dynamically update the paragraph element with how many points the customer needs to reach the next tier. -->
Output:
Earn 634 more points to reach Gold
Read the docs
REST API
What can I do with it?
The Rivo REST API allows you to programmatically manage and interact with your loyalty program. With this API, you can retrieve and update customer data, redeem rewards, create referrals and points events and more.
Where can I use it?
The REST API must be run server-side. It can be integrated into any external system or application that requires access to Rivo’s loyalty program data. This makes it ideal for use in custom backend processes, server-side applications, and third-party integrations
Key Functions:
Manage Customers: Retrieve and update customer details, such as birthday and VIP tier.
Handle Rewards: List available rewards and manage redemptions.
Points Events: Create points events for customers such as custom actions or social follows.
Track Referrals: Create and manage referral activities.
Set Up Webhooks: Receive real-time notifications for key loyalty events.
Example usage
Here’s how you might use the REST API to return a single customer’s data:
curl --request GET \
--url https://developer-api.rivo.io/merchant_api/v1/customers/7855248179442 \
--header 'Authorization: 11xxxxf9xxxxxxxx10e5xxx0bf'
Response:
{
"data": {
"type": "customer",
"id": 7855248179442,
"attributes": {
"id": 7855248179442,
"email": "[email protected]",
"first_name": "Laurence",
"last_name": "orderTEst",
"accepts_marketing": false,
"orders_count": 0,
"verified_email": false,
"total_spent": 0,
"shopify_tags": [],
"loyalty_status": "member",
"points_tally": 110,
"credits_tally": "0.0",
"dob": null,
"dob_last_updated_at": null,
"referral_url": "https://feblaurloy.myshopify.com/collections/all?referral_code=YAWepL9eS9DLGk4DD",
"referral_code": "YAWepL9eS9DLGk4DD",
"vip_tier": {
"id": 168703,
"name": "Bronze",
"threshold": 0,
"perks": [],
"icon_url": null,
"desc": null,
"rewards": []
},
"points_expire_at": null
}
}
}
<!-- This example demonstrates how to retrieve detailed information about a specific customer using their unique identifier. The response includes customer details such as email, loyalty status, points balance, VIP tier, and more. -->
Read the docs