How to use 99minds Loyalty SDK

Getting Started

To get started, you need to initialize the SDK with the necessary configuration options. The Loyalty class is the main entry point for interacting with the SDK.

Usage

Change the script URL as per the environment:

Environment	URL
PRODUCTION	https://assets.99minds.io/live/loyalty-sdk/bundle.js
ENTERPRISE1	https://assets.99minds.io/enterprise1/loyalty-sdk/bundle.js
STAGING	https://assets.99minds.io/staging/loyalty-sdk/bundle.js
QA	https://assets.99minds.io/qa/loyalty-sdk/bundle.js
DEV	https://assets.99minds.io/dev/loyalty-sdk/bundle.js

After that Generate API key from Settings > API with scope STOREFRONT.LOYALTY and copy the Key ID to apiKey below:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>99minds Loyalty SDK Example</title>
    <script src="https://assets.99minds.io/live/loyalty-sdk/bundle.js"></script>
</head>
<body>
    <script>
        window.sdk = new MindsSDK.Loyalty({
            apiKey: 'your-api-key',
            platform: 'SHOPIFY',
            shopDomain: 'your-shop-domain.myshopify.com',
            useAppProxy: false,  // Default is true for Shopify
            getCurrentCustomer: async () => 'customer-id',
        });
    </script>
</body>
</html>

Since the SDK initializes asynchronously, you need to wait before accessing its resources. Here are two ways to do it:

Option 1: Listening for the Event

For users who want to listen for the event:

document.addEventListener('MindsSDKInitialized', (event) => {
  const sdk = event.detail.sdk;

  (async () => {
    try {
      const pointsBalance = await sdk.resource.getPointsBalance();
      console.log('Points:', pointsBalance);
    } catch (error) {
      console.error('Error fetching points:', error);
    }
  })();
});

Option 2: Using the Promise

For users who prefer to use the promise-based approach:

(async () => {
  try {
    const sdk = await window.sdk.onReady(); // Wait for SDK to be ready
    const pointsBalance = await sdk.resource.getPointsBalance();
    console.log('Points:', pointsBalance);
  } catch (error) {
    console.error('Error fetching points:', error);
  }
})();

Full example:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>99minds Loyalty SDK Example</title>
    <script src="https://assets.99minds.io/live/loyalty-sdk/bundle.js"></script>
</head>
<body>
    <script>
        const sdk = new MindsSDK.Loyalty({
            apiKey: 'your-api-key',
            platform: 'SHOPIFY',
            shopDomain: 'your-shop-domain.myshopify.com',
            useAppProxy: false,  // Default is true for Shopify
            getCurrentCustomer: async () => 'customer-id',
        });

        // Since the SDK initializes asynchronously, you need to wait before accessing its resources.
        // Here are two ways to do it:

        // Option 1: Listening for the Event
        document.addEventListener('MindsSDKInitialized', (event) => {
            const sdk = event.detail.sdk;
            (async () => {
                try {
                    const pointsBalance = await sdk.resource.getPointsBalance();
                    console.log('Points:', pointsBalance);
                } catch (error) {
                    console.error('Error fetching points:', error);
                }
            })();
        });

        // Option 2: Using the Promise
        (async () => {
            try {
                const sdk = await window.sdk.onReady(); // Wait for SDK to be ready
                const pointsBalance = await sdk.resource.getPointsBalance();
                console.log('Points:', pointsBalance);
            } catch (error) {
                console.error('Error fetching points:', error);
            }
        })();
    </script>
</body>
</html>

Reference

SDK Classes

The SDK provides three main classes for different use cases:

LoyaltyWidget Class

The LoyaltyWidget class is designed for embedding loyalty widgets within your application. It provides access to loyalty resources with the LOYALTY_WIDGET API scope.

LoyaltyPage Class

The LoyaltyPage class is designed for full loyalty page implementations. It provides access to loyalty resources with the LOYALTY_PAGE API scope, which may include additional functionality compared to the widget scope.

Loyalty Class (Legacy)

The Loyalty class is a child of LoyaltyWidget and is maintained for backward compatibility. New implementations should use either LoyaltyWidget or LoyaltyPage based on your use case.

Constructor Arguments

All three classes accept the same constructor options through the LoyaltyOptions interface:

Parameter	Type	Required	Default Value	Description
`apiKey`	`string`	Yes	None	API key for authentication (scope: `STOREFRONT.LOYALTY`)
`platform`	`string`	Yes	None	Platform type (e.g., 'SHOPIFY', 'BIGCOMMERCE')
`shopDomain`	`string`	No	None	Required when platform is SHOPIFY and useAppProxy is false
`useAppProxy`	`boolean`	No	`platform === 'SHOPIFY'`	Whether to use app proxy (defaults to true for Shopify)
`dom`	`boolean`	No	`true`	Whether to emit DOM events
`getCurrentCustomer`	`() => Promise<string>`	No	None	Function to get current customer ID

Class Usage Examples

// For loyalty widgets
const widget = new MindsSDK.LoyaltyWidget({
    apiKey: 'your-api-key',
    platform: 'SHOPIFY',
    shopDomain: 'your-shop-domain.myshopify.com',
    getCurrentCustomer: async () => 'customer-id',
});

// For loyalty pages
const page = new MindsSDK.LoyaltyPage({
    apiKey: 'your-api-key',
    platform: 'SHOPIFY',
    shopDomain: 'your-shop-domain.myshopify.com',
    getCurrentCustomer: async () => 'customer-id',
});

// Legacy compatibility (uses LoyaltyWidget internally)
const legacy = new MindsSDK.Loyalty({
    apiKey: 'your-api-key',
    platform: 'SHOPIFY',
    shopDomain: 'your-shop-domain.myshopify.com',
    getCurrentCustomer: async () => 'customer-id',
});

All classes provide access to various resources based on the platform you are using. The available platforms include Shopify, BigCommerce, and a default base resource for other platforms.

Resources

Promises

The methods provided by the SDK to interact with the various resources and endpoints return a Promise. This means that you can use .then() and .catch() to handle the result of the API calls, or you can use the async/await syntax for a more modern and readable approach.

Example with `.then()` and `.catch()`

sdk.resource.getRewards()
    .then(rewards => {
        console.log('Rewards:', rewards);
    })
    .catch(error => {
        console.error('Error fetching rewards:', error);
    });

Example with `async/await`

(async () => {
    try {
        const rewards = await sdk.resource.getRewards();
        console.log('Rewards:', rewards);
    } catch (error) {
        console.error('Error fetching rewards:', error);
    }
})();

Using promises ensures that you can easily manage asynchronous operations, such as fetching data from the API, and handle any errors that might occur during the process.

Get Info

Fetch basic information about the loyalty program.

const info = await sdk.resource.getInfo();

Get Rewards

Retrieve the rewards available to the current customer.

const rewards = await sdk.resource.getRewards();

Get Points Balance

Get the current points balance for the customer.

const pointsBalance = await sdk.resource.getPointsBalance();

Get Store Credits Balance

Get the current store credits balance for the customer.

const storeCreditsBalance = await sdk.resource.getStoreCreditsBalance();

Get Points Transactions

Retrieve the list of points transactions for the customer.

const pointsTransactions = await sdk.resource.getPointsTransactions();

Get Store Credits Transactions

Retrieve the list of store credits transactions for the customer.

const storeCreditsTransactions = await sdk.resource.getStoreCreditsTransactions();

Get Referral Details

Get details about the customer's referral program.

const referralDetails = await sdk.resource.getReferralDetails();

Post Social Media Rewards

Post rewards for social media actions.

const response = await sdk.resource.postSocialMediaRewards({
  client_customer_id: 'customer-id',
  type: 'FACEBOOK_LIKE'
});

Post Redeem Points

Redeem points for rewards.

const response = await sdk.resource.postRedeemPoints({
  client_customer_id: 'customer-id',
  amount: 20
});

Post Referral Accept

Accept a referral using a code.

const response = await sdk.resource.postReferralAccept({
  client_customer_id: 'customer-id',
  code: 'ABCXYZ'
});

Post Update Customer

Update customer details.

const response = await sdk.resource.postUpdateCustomer({
  client_customer_id: 'customer-id',
  customer: {
    birthday_str: '03/25',
    opt_in_loyalty: true
  }
});

Post Customer

Add, Update or Fetch a customer.

const response = await sdk.resource.postCustomer({
  client_customer_id: 'customer-id',
  name: 'John Doe',
  email: '[email protected]',
  phone: '+19178245476'
});

Get Customer Metrics

Fetch a customer's metrics like total_spent and order_count.

const response = await sdk.resource.getCustomerMetrics({
  client_customer_id: 'customer-id',
  ...params
});

Parameter	Required	Description
min	No	Minimum timestamp (in UNIX format) to filter metrics. Only records created on or after this timestamp will be included.
max	No	Maximum timestamp (in UNIX format) to filter metrics. Only records created on or before this timestamp will be included.
platform	No	Platform identifier (e.g., `SHOPIFY`, `BIGCOMMERCE`, `HEARTLAND_RETAIL`, etc.). If not specified, defaults to `ALL`, returning metrics aggregated across all supported platforms.

Configuration

The SDK is highly configurable. You can pass various options when initializing the Loyalty class, including the API key, platform, shop domain (for Shopify), and whether to use an app proxy.

Example:

const sdk = new Loyalty({
  apiKey: 'your-api-key',
  platform: 'BIGCOMMERCE',
  useAppProxy: false,
  getCurrentCustomer: async () => 'customer-id',
});

Support

If you encounter any issues or have any questions, please reach out to our support team at [email protected].

How To Setup 99minds Loyalty Page On Your Website

How To Add 99minds Loyalty Widget On Your Website

How to Redeem Loyalty Points & Apply Coupons in 99minds on Shopify POS