Skip to main content

​
JavaScript SDK

The Mage JavaScript SDK is a lightweight client-side library that lets you build custom loyalty experiences directly in your storefront. Once enabled, the SDK is bundled into your storefront and available as window.MageSDK.

​
Enable the SDK

Enable the Mage JavaScript SDK from the merchant dashboard under Settings > Developer. Once enabled, the SDK is automatically injected into your storefront.

​
Initialization

The SDK loads asynchronously. Use the mage-sdk-loaded event to ensure it’s ready before calling any methods: 
if (window.MageSDK) {
  // MageSDK is loaded and ready to use
} else {
  document.addEventListener('mage-sdk-loaded', function() {
    // MageSDK is loaded and ready to use
  });
}

​
Response format

All methods return a consistent response shape: Success: 
{
  "success": true,
  "data": { ... }
}
Error: 
{
  "success": false,
  "error": "Customer not logged in"
}

​
Common errors

ErrorCause
"Unauthorized"No Shopify session (customer not on the store)
"Customer not found"Customer is not logged in or not enrolled
"Customer is excluded from the loyalty program"Customer has been excluded by the merchant
"Network error"Failed to reach the API

​
Available methods

Customers

Retrieve customer details, VIP tier, and update profile

Rewards

List rewards, view redeemed rewards, and redeem points

VIP Tiers

List all VIP tier configurations

Earning Rules

List active earning rules

Referrals

Referral stats, links, and social sharing

Sidebar

Programmatically open and close the loyalty sidebar