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

All methods return a consistent response shape:

**Success:**

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

**Error:**

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

## 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     |
| `"Network error"`                                 | Failed to reach the API                        |

## Available methods

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

  <Card title="Rewards" icon="gift" href="/js-sdk/rewards/get-shop-rewards">
    List rewards, view redeemed rewards, and redeem points
  </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
  </Card>

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

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