> ## Documentation Index
> Fetch the complete documentation index at: https://developers.mageloyalty.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

> The Mage JavaScript SDK gives you client-side access to your loyalty program from any Shopify storefront.

## 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:

```javascript theme={null}
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:**

```json theme={null}
{
  "success": true,
  "data": { ... }
}
```

**Error:**

```json theme={null}
{
  "success": false,
  "error": "Customer not logged in"
}
```

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

## 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`](/js-sdk/loyalty-modes) helper and it renders correctly in either mode, so your code stays mode-agnostic. See the [Loyalty modes](/js-sdk/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`](/js-sdk/rewards/redeem-flexible) instead |
| `"Network error"` | Failed to reach the API |

## Available methods

<CardGroup cols={2}>
  <Card title="Customers" icon="user" href="/js-sdk/customers/get-customer-details">
    Customer details, VIP tier, activity feed, and profile updates
  </Card>

  <Card title="Rewards" icon="gift" href="/js-sdk/rewards/get-shop-rewards">
    List rewards, view redeemed rewards, and redeem points or store credit
  </Card>

  <Card title="VIP Tiers" icon="crown" href="/js-sdk/vip-tiers/get-shop-vip-tiers">
    List all VIP tier configurations
  </Card>

  <Card title="Earning Rules" icon="coins" href="/js-sdk/earning-rules/get-earning-rules">
    List active earning rules with tier and campaign boosts
  </Card>

  <Card title="Referrals" icon="share" href="/js-sdk/referrals/get-customer-referral-stats">
    Referral stats, links, and social sharing
  </Card>

  <Card title="Loyalty modes" icon="money-bill" href="/js-sdk/loyalty-modes">
    Format and redeem correctly in points and store-credit shops
  </Card>

  <Card title="Sidebar" icon="sidebar" href="/js-sdk/sidebar/open-sidebar">
    Programmatically open and close the loyalty sidebar
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.