Introduction - Mage Loyalty Documentation

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

Most methods return a consistent response shape: Success:

{
  "success": true,
  "data": { ... }
}

Error:

{
  "success": false,
  "error": "Customer not logged in"
}

updateCustomerDob is the one exception. It returns a plain boolean rather than the wrapped response shape, for backwards compatibility.

Loyalty modes

A shop runs in one of two loyalty modes, set by the merchant:

points The loyalty balance is plain points, so 450 means 450 points.
store_credit The balance is Mage store credit, denominated in money. Every loyalty number the SDK returns (points, pointsCost, balances) is in the currency’s minor units, so 450 means $4.50.

Methods that carry loyalty amounts also return loyaltyMode and currency. Pass both to the built-in formatLoyaltyValue helper and it renders correctly in either mode, so your code stays mode-agnostic. See the Loyalty modes guide for the full picture, including how redemption differs.

Common errors

Error	Cause
`"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
`"This reward cannot be redeemed in store credit mode"`	Fixed-cost redemption attempted on a store-credit shop. Use `redeemFlexible` instead
`"Network error"`	Failed to reach the API

Available methods

Customers

Customer details, VIP tier, activity feed, and profile updates

Rewards

List rewards, view redeemed rewards, and redeem points or store credit

VIP Tiers

List all VIP tier configurations

Earning Rules

List active earning rules with tier and campaign boosts

Referrals

Referral stats, links, and social sharing

Loyalty modes

Format and redeem correctly in points and store-credit shops

Sidebar

Programmatically open and close the loyalty sidebar

​JavaScript SDK

​Enable the SDK

​Initialization

​Response format

​Loyalty modes

​Common errors

​Available methods

Customers

Rewards

VIP Tiers

Earning Rules

Referrals

Loyalty modes

Sidebar

JavaScript SDK

Enable the SDK

Initialization

Response format

Loyalty modes

Common errors

Available methods