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?
✨ Developer Toolkit access depends on your Rivo plan and enabled features. If you do not see these settings, contact your Rivo customer success manager.
From your Rivo dashboard, go to Settings > Developer Toolkit. Most stores will see these 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.
Rivo supports shop-level loyalty metafields and customer-level loyalty metafields. The exact metafield keys available on your store can depend on your setup and the version of metafields enabled for your account.
shop.metafields.rivo.loy
customer.metafields.custom.rivo.value
Newer customer metafields may also appear as individual Rivo customer metafields in Shopify, such as a customer points balance metafield.
Could not display content
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
Could not display content
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
Could not display content
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. -->
Could not display content
Current balance vs. lifetime points earned
The points_tally field in the customer response is the customer’s current points balance. It is not the same as the total number of points the customer has earned over time.
To return the customer’s lifetime earned tally for a single customer, include the lifetime_earnings_tally field on the customer request:
curl --request GET \
--url "https://developer-api.rivo.io/merchant_api/v1/customers/7855248179442?fields=lifetime_earnings_tally" \
--header 'Authorization: 11xxxxf9xxxxxxxx10e5xxx0bf'
The response includes lifetime_earnings_tally in the customer’s attributes when that field is requested.
If you need to audit the individual events behind a customer’s balance, use the points events endpoint filtered to that customer and page through the results:
curl --request GET \
--url "https://developer-api.rivo.io/merchant_api/v1/points_events?filters[customer_identifier]=7855248179442&pagination[since_id]=0&pagination[limit]=250&sort[order_direction]=asc" \
--header 'Authorization: 11xxxxf9xxxxxxxx10e5xxx0bf'
Use the paginated points events response when you need the event history, event dates, notes, or source details. Use lifetime_earnings_tally when you only need the total lifetime earned value for one customer.
Data Freshness and Rate Limits
If you’re syncing Rivo data into a data warehouse or external app, use these expectations:
Customer balances and manual points events: Usually available immediately after the event is processed.
Order-based loyalty updates: Processed asynchronously from Shopify webhooks and background jobs, so updates are typically near-real-time and can take a few minutes in busy periods.
Analytics/reporting metrics: Aggregated on scheduled jobs, so analytics views can lag behind raw customer and points event data.
Merchant API rate limits
Default limit: 15 requests per second per store
If you exceed the limit, the API returns 429 with:
Build retry logic with exponential backoff, and follow the
Retry-Afterheader before retrying.