Skip to main content

JavaScript SDK

Add loyalty widgets to your frontend without building from scratch.

Installation​

npm install loyali-sdk
View on npm →

Quick Start​

import { Loyali } from 'loyali-sdk';

const loyali = new Loyali({
  apiUrl: 'https://api.loyali.io/api/v1',
  publicKey: 'pk_live_YOUR_KEY'  // Get from Dashboard → Settings → API Keys
});

// Identify the current user
const customer = await loyali.identify({
  external_reference: 'your-user-id'
});

console.log(`${customer.first_name} has ${customer.points_balance} points`);
Public Keys

The SDK uses public keys (pk_live_...) which are safe to expose in browser code. They can only read data, not modify it.

Getting Your Public Key​

  1. Go to Dashboard
  2. Navigate to Settings → API Keys
  3. Create a key with type Public
  4. Copy the key (pk_live_...)

Methods​

Identify Customer​

const customer = await loyali.identify({
  external_reference: 'your-user-id'
});

Returns the customer's profile, points, and tier.

View in API Reference →

Get Points Balance​

const points = await loyali.getPoints();
// { balance: 1500, lifetime_earned: 2500 }

Get Available Rewards​

const { rewards } = await loyali.getRewards();
// Array of rewards the customer can redeem

Get Activity History​

const { activities } = await loyali.getActivity(10);
// Last 10 point transactions

Get Portal URL​

const portalUrl = loyali.getPortalUrl();
// Redirect user here to redeem rewards
window.location.href = portalUrl;

React Integration​

import { LoyaliProvider, useLoyali } from 'loyali-sdk/react';

function App() {
  return (
    <LoyaliProvider
      apiUrl="https://api.loyali.io/api/v1"
      publicKey="pk_live_YOUR_KEY"
    >
      <LoyaltyWidget />
    </LoyaliProvider>
  );
}

function LoyaltyWidget() {
  const { customer, loading, identify } = useLoyali();
  
  useEffect(() => {
    identify({ external_reference: currentUser.id });
  }, [currentUser]);
  
  if (loading) return <Spinner />;
  if (!customer) return null;
  
  return (
    <div>
      <p>{customer.points_balance} points</p>
      <a href={loyali.getPortalUrl()}>Redeem Rewards →</a>
    </div>
  );
}

Pre-built Widgets​

Drop-in UI components:

import { PointsCounter, RewardsGrid, TierProgress } from 'loyali-sdk/widgets';

// Points display
new PointsCounter({ container: '#points' }).render(loyali);

// Rewards catalog
new RewardsGrid({ container: '#rewards' }).render(loyali);

// Tier progress bar
new TierProgress({ container: '#tier' }).render(loyali);

Theming​

Match your brand:

const loyali = new Loyali({
  apiUrl: 'https://api.loyali.io/api/v1',
  publicKey: 'pk_live_...',
  theme: {
    primaryColor: '#8b5cf6',
    backgroundColor: '#0a0a0f',
    textColor: '#ffffff'
  }
});

Customer Portal​

Don't want to build your own redemption UI?

Send customers to the white-label portal:

const portalUrl = loyali.getPortalUrl();
// https://portal.loyali.io/org/your-org

The portal lets customers:

  • View their points and tier
  • Browse available rewards
  • Redeem rewards
  • See their history

All styled with your organization's branding (configurable in Dashboard).

Full API Reference​

For all SDK endpoints, see the SDK section in the API Reference:

View SDK Endpoints →