Skip to main content

Quick Start

Get your loyalty program running in under an hour. This guide walks you through everything step-by-step.

Choose Your Path​

No-Code (Dashboard)​

Perfect for testing, non-technical setup, or quick demos.

Time: 15 minutes
Best for: Marketers, product managers, testing

  1. Go to dashboard.loyali.io
  2. Click Customers → Add Customer
  3. Click Award Points on any customer
  4. Create rewards in Rewards → Add Reward
  5. Test redemption in Customers → Redeem Reward

Done! Your loyalty program is live.

API Integration​

For developers who want to automate and integrate.

Time: 30-60 minutes
Best for: Developers, production integrations

Keep reading below for the complete API quickstart with code examples.

Prerequisites​

Before you start, you'll need:

  1. ✅ A Loyali account - Sign up free (no credit card required)
  2. ✅ API Key - Get from Dashboard → Settings → API Keys
  3. ✅ Basic coding knowledge - This guide uses JavaScript/Node.js examples

Step 1: Get Your API Key​

In Dashboard​

  1. Go to dashboard.loyali.io
  2. Navigate to Settings → API Keys
  3. Click Create API Key
  4. Select Private Key (for server-side use)
  5. Copy the key immediately - you won't see it again!

Your key will look like: sk_live_abc123def456...

Keep Your Key Secret

Private keys (sk_live_...) should never be exposed in frontend code, mobile apps, or public repositories. Always use them server-side only.

Test Your Key​

curl https://api.loyali.io/api/v1/customers \
  -H "X-API-Key: sk_live_YOUR_KEY"

If you see an empty array [], your key works! 🎉

Step 2: Create Your First Customer​

When someone signs up for your app, add them to Loyali.

Basic Example​

// Using fetch (browser or Node.js 18+)
async function createCustomer(email, firstName, lastName, userId) {
  const response = await fetch('https://api.loyali.io/api/v1/customers', {
    method: 'POST',
    headers: {
      'X-API-Key': 'sk_live_YOUR_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      email: email,
      first_name: firstName,
      last_name: lastName,
      external_reference: userId.toString()  // Your user ID
    })
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.message);
  }

  return await response.json();
}

// Usage
const customer = await createCustomer(
  'alex@example.com',
  'Alex',
  'Johnson',
  'user_12345'
);

console.log('Customer created:', customer.id);

Using cURL​

curl -X POST https://api.loyali.io/api/v1/customers \
  -H "X-API-Key: sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "alex@example.com",
    "first_name": "Alex",
    "last_name": "Johnson",
    "external_reference": "user_12345"
  }'

Response:

{
  "id": "cust_abc123",
  "email": "alex@example.com",
  "first_name": "Alex",
  "last_name": "Johnson",
  "external_reference": "user_12345",
  "points_balance": 0,
  "tier": null,
  "created_at": "2024-01-15T10:30:00Z"
}

Using the JavaScript SDK​

import { Loyali } from 'loyali-sdk';

const loyali = new Loyali({
  apiUrl: 'https://api.loyali.io/api/v1',
  apiKey: 'sk_live_YOUR_KEY'  // Private key for server-side
});

const customer = await loyali.customers.create({
  email: 'alex@example.com',
  first_name: 'Alex',
  last_name: 'Johnson',
  external_reference: 'user_12345'
});
💡 Tip: Use external_reference to store your own user ID. This makes it easy to find the Loyali customer when you only have your user ID.
View Full API Reference →

Step 3: Award Points​

When a customer makes a purchase, award them points.

Basic Example: Fixed Points​

async function awardPoints(customerId, points, description, reference) {
  const response = await fetch(
    `https://api.loyali.io/api/v1/customers/${customerId}/points/transaction`,
    {
      method: 'POST',
      headers: {
        'X-API-Key': 'sk_live_YOUR_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        amount: points,
        type: 'earn',
        description: description,
        reference: reference  // Prevents duplicates
      })
    }
  );

  return await response.json();
}

// Award 150 points for a purchase
await awardPoints(
  'cust_abc123',
  150,
  'Purchase - Order #1234',
  'order_1234'  // Use order ID to prevent duplicate awards
);

Advanced Example: Points Based on Purchase Amount​

async function awardPointsForPurchase(customerId, orderTotal, orderId) {
  // Calculate points: 1 point per dollar spent
  const points = Math.floor(orderTotal);
  
  const response = await fetch(
    `https://api.loyali.io/api/v1/customers/${customerId}/points/transaction`,
    {
      method: 'POST',
      headers: {
        'X-API-Key': 'sk_live_YOUR_KEY',
        'Content-Type': 'application/json',
        'Idempotency-Key': `order_${orderId}`  // Prevents duplicates
      },
      body: JSON.stringify({
        amount: points,
        type: 'earn',
        description: `Purchase - Order #${orderId}`,
        reference: `order_${orderId}`,
        metadata: {
          order_total: orderTotal,
          order_id: orderId,
          currency: 'USD'
        }
      })
    }
  );

  if (!response.ok) {
    const error = await response.json();
    // Check if it's a duplicate (already processed)
    if (error.code === 'duplicate_transaction') {
      console.log('Points already awarded for this order');
      return;
    }
    throw new Error(error.message);
  }

  const result = await response.json();
  console.log(`Awarded ${result.amount} points. New balance: ${result.balance}`);
  
  return result;
}

// Usage: Customer spends $125.50
await awardPointsForPurchase('cust_abc123', 125.50, 'order_1234');
// Awards 125 points
💡 Tip: Always use the reference or Idempotency-Key header to prevent duplicate point awards if you retry a request.
View Full API Reference →

Step 4: Check Customer Status​

Get a customer's complete profile including points, tier, and recent activity.

Get Customer Summary​

async function getCustomerSummary(customerId) {
  const response = await fetch(
    `https://api.loyali.io/api/v1/customers/${customerId}/summary`,
    {
      headers: {
        'X-API-Key': 'sk_live_YOUR_KEY'
      }
    }
  );

  return await response.json();
}

const summary = await getCustomerSummary('cust_abc123');
console.log('Points balance:', summary.points.balance);
console.log('Current tier:', summary.tier?.current?.name || 'None');
console.log('Next tier:', summary.tier?.next?.name);
console.log('Points needed:', summary.tier?.next?.points_needed);

Response:

{
  "customer": {
    "id": "cust_abc123",
    "email": "alex@example.com",
    "first_name": "Alex",
    "last_name": "Johnson"
  },
  "points": {
    "balance": 150,
    "lifetime_earned": 150,
    "lifetime_redeemed": 0
  },
  "tier": {
    "current": null,
    "next": {
      "name": "Silver",
      "points_threshold": 1000,
      "points_needed": 850
    }
  },
  "recent_activity": [
    {
      "type": "earn",
      "amount": 150,
      "description": "Purchase - Order #1234",
      "created_at": "2024-01-15T10:35:00Z"
    }
  ]
}

Display Points in Your App​

// Frontend example (using public key)
import { Loyali } from 'loyali-sdk';

const loyali = new Loyali({
  apiUrl: 'https://api.loyali.io/api/v1',
  publicKey: 'pk_live_YOUR_PUBLIC_KEY'  // Safe for browser
});

// Identify customer by your user ID
const customer = await loyali.identify({
  external_reference: currentUser.id.toString()
});

// Display points
document.getElementById('points-balance').textContent = 
  `${customer.points_balance} points`;

// Display tier progress
if (customer.tier) {
  document.getElementById('tier-status').textContent = 
    `${customer.tier.name} Member`;
} else {
  const nextTier = customer.tier_next;
  document.getElementById('tier-status').textContent = 
    `${nextTier.points_needed} points until ${nextTier.name}`;
}
💡 Tip: Use public keys (pk_live_...) in frontend code. They're read-only and safe to expose. Get them from Dashboard → Settings → API Keys → Create Public Key.
View Full API Reference →

Step 5: Create Rewards​

Give customers something to redeem their points for.

Create a Digital Reward​

async function createReward(title, pointsCost, description) {
  const response = await fetch('https://api.loyali.io/api/v1/rewards', {
    method: 'POST',
    headers: {
      'X-API-Key': 'sk_live_YOUR_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      title: title,
      points_cost: pointsCost,
      reward_type: 'digital',
      description: description,
      stock_quantity: null  // null = unlimited
    })
  });

  return await response.json();
}

// Create a $10 discount reward
const reward = await createReward(
  '$10 Off Your Next Order',
  1000,  // Costs 1,000 points
  'Use this discount code at checkout. Valid for 30 days.'
);

console.log('Reward created:', reward.id);

Create Multiple Rewards​

const rewards = [
  {
    title: '$5 Off Your Next Order',
    points_cost: 500,
    description: 'Instant discount code'
  },
  {
    title: '$10 Off Your Next Order',
    points_cost: 1000,
    description: 'Instant discount code'
  },
  {
    title: 'Free Shipping',
    points_cost: 500,
    description: 'Free shipping on your next order'
  },
  {
    title: '$25 Gift Card',
    points_cost: 2500,
    description: 'Digital gift card delivered via email'
  }
];

for (const rewardData of rewards) {
  await createReward(
    rewardData.title,
    rewardData.points_cost,
    rewardData.description
  );
}
💡 Tip: Offer rewards at different point levels (500, 1,000, 2,500, 5,000) so customers have goals at every stage.
View Full API Reference →

Create membership levels that reward loyal customers.

Create Tier Structure​

async function createTier(name, threshold, multiplier, benefits) {
  const response = await fetch('https://api.loyali.io/api/v1/tiers', {
    method: 'POST',
    headers: {
      'X-API-Key': 'sk_live_YOUR_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: name,
      points_threshold: threshold,
      multiplier: multiplier,
      benefits: benefits
    })
  });

  return await response.json();
}

// Bronze (entry level)
await createTier('Bronze', 0, 1.0, [
  'Base earning rate'
]);

// Silver (engaged customers)
await createTier('Silver', 1000, 1.25, [
  '1.25x points on all purchases',
  'Free shipping on orders $50+'
]);

// Gold (loyal customers)
await createTier('Gold', 5000, 1.5, [
  '1.5x points on all purchases',
  'Free shipping always',
  'Early access to sales'
]);

What happens:

  • Customers automatically upgrade when they reach thresholds
  • Higher tiers earn points faster (multiplier)
  • You'll receive a tier.upgraded webhook when someone upgrades
Learn more about tiers →

Step 7: Automate with Events (Advanced)​

Instead of manually awarding points, use events to automate everything.

Set Up an Event Type​

async function createEventType(name, displayName, defaultPoints) {
  const response = await fetch('https://api.loyali.io/api/v1/event-types', {
    method: 'POST',
    headers: {
      'X-API-Key': 'sk_live_YOUR_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: name,
      display_name: displayName,
      default_points: defaultPoints
    })
  });

  return await response.json();
}

// Create purchase event type
await createEventType('purchase', 'Purchase', 0);

Send Events Instead of Direct Points​

async function sendPurchaseEvent(customerId, orderTotal, orderId) {
  const response = await fetch('https://api.loyali.io/api/v1/events', {
    method: 'POST',
    headers: {
      'X-API-Key': 'sk_live_YOUR_KEY',
      'Content-Type': 'application/json',
      'Idempotency-Key': `event_order_${orderId}`
    },
    body: JSON.stringify({
      customer_id: customerId,
      event_type: 'purchase',
      properties: {
        amount: orderTotal,
        order_id: orderId
      },
      reference: `order_${orderId}`
    })
  });

  const result = await response.json();
  console.log(`Points awarded: ${result.points_awarded}`);
  
  return result;
}

// Send event - points calculated automatically based on rules
await sendPurchaseEvent('cust_abc123', 125.50, 'order_1234');

Benefits:

  • Points calculated automatically based on rules
  • Easy to change point values without code changes
  • Better analytics on customer behavior
Learn more about events →

Step 8: Test the Complete Flow​

Let's test everything end-to-end:

// 1. Create a customer
const customer = await createCustomer(
  'test@example.com',
  'Test',
  'User',
  'test_user_123'
);

// 2. Award points for a purchase
await awardPointsForPurchase(customer.id, 150.00, 'test_order_1');

// 3. Check their status
const summary = await getCustomerSummary(customer.id);
console.log('Balance:', summary.points.balance);  // Should be 150

// 4. Create a reward
const reward = await createReward('$5 Off', 100, 'Test reward');

// 5. Redeem reward (in Dashboard or via API)
// Customer now has 50 points remaining

// 6. Check status again
const updatedSummary = await getCustomerSummary(customer.id);
console.log('New balance:', updatedSummary.points.balance);  // Should be 50

What's Next?​

Set Up Tiers​

Create Bronze → Silver → Gold membership levels that unlock automatically.

Tiers Guide →

Automate Points​

Use Events to automatically award points for purchases, signups, and more.

Events Guide →

Add Frontend Widgets​

Drop in the JavaScript SDK for instant UI components.

SDK Guide →

Get Real-time Updates​

Set up webhooks to react to events instantly.

Webhooks Guide →

See Real Examples​

Learn from successful implementations.

Use Cases →

Optimize Your Program​

Follow best practices to maximize engagement.

Best Practices →

Common Questions​

How do I prevent duplicate point awards?​

Use the reference field or Idempotency-Key header with a unique value (like your order ID). If you send the same reference twice, we'll return the existing transaction instead of creating a duplicate.

Can I use this in production?​

Yes! Loyali is production-ready with 99.9% uptime SLA. Start with the free plan (1,000 customers) and upgrade as you grow.

What if I make a mistake?​

You can manually adjust points in the Dashboard, or use the API to create adjustment transactions. Points history is always preserved for auditing.

How do I display points in my frontend?​

Use the JavaScript SDK with a public key (safe for browsers). See the SDK Guide for examples.

Need help?​

Email us at support@loyali.io or check the API Reference.