Introduction
BrandLift's Developer Resources enable programmers to tailor and enhance the BrandLift loyalty system to suit their unique requirements. This document outlines the primary tools available within the resource kit:
- Metafields: Metafields offer a method for utilizing and showcasing information linked to customers and your rewards program. These can be incorporated into Shopify theme layouts and bespoke elements to dynamically present loyalty-related details.
- BrandLiftJS API: This JavaScript library is intended for frontend implementation within your Shopify store. It enables you to retrieve and exhibit loyalty information, such as point totals and loyalty tiers, directly on your website, as well as execute essential operations like reward redemption and customer birthday updates.
- REST API: The RESTful interface facilitates backend integration, allowing you to oversee and interact with your loyalty scheme by fetching and modifying customer information, handling rewards, and monitoring referrals. It's particularly suited for server-side processes and integrations with external platforms.
How do I enable the Developer Toolkit?
From your BrandLift 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.
- BrandLift Javascript API - Toggle this on to include the BrandLift Javascript API on the storefront.
- BrandLift Shopify Metafields - Toggle this switch to enable BrandLift metafields (customer metafields can take some time to sync, depending on the customer count.)
Metafields
What can I do with them?
Leverage metafields to dynamically showcase and utilize information about the currently logged-in customer and your store's loyalty program configurations.
We have two metafields, one for shop data and one for customer data:
shop.metafields.brandlift.loy
customer.metafields.custom.brandlift.value
Where can I use them?
Shopify theme templates and customizable blocks within the theme editor support the use of metafields, provided these blocks are compatible with Liquid. However, metafields cannot be implemented in static HTML files outside of these specific environments. Make sure to insert them in areas that support Liquid code execution.
Example usage
<div>You have {{ customer.metafields.custom.brandlift.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.brandlift.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
Read the docs
- Getting Started with BrandLift Metafields
- Shop object metafields
- Customer object metafields
BrandLiftJS API
What can I do with it?
The BrandLift JavaScript API provides access to information related to the active customer and loyalty program settings. You can obtain crucial customer data, including point transaction history, referral information, current point balance, and VIP tier advancement, and integrate it directly into your store's frontend. Furthermore, the API enables two primary functions: reward redemption and customer birthday updates.
Where can I use it?
You can implement the BrandLiftJS API in most areas of your Shopify storefront where JavaScript is supported. It's integrated into your store via our theme app extensions, which means certain sections like the checkout process and the updated customer account page are not compatible.
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 BrandLiftJS 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("brandlift-js-loaded", function() {
BrandLiftJS.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 brandlift-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
- Getting Started & Events
- BrandLiftJS functions
- Examples
REST API
What can I do with it?
BrandLift's REST API provides programmatic access to manage and interact with your loyalty program. This API enables you to fetch and modify customer information, process reward redemptions, generate referrals and points transactions, among other functionalities.
Where can I use it?
It's essential to run the REST API on the server side. The API can be seamlessly incorporated into any external platform or software requiring access to BrandLift's loyalty program information. This makes it particularly suitable for customized backend operations, server-based applications, and integrations with third-party systems.
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.brandlift.io/merchant_api/v1/customers/7855248179442 \
--header 'Authorization: 11xxxxf9xxxxxxxx10e5xxx0bf'
Response:
{
"data": {
"type": "customer",
"id": 7855248179442,
"attributes": {
"id": 7855248179442,
"email": "laurence+testorder@brandLift.io",
"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. -->