Skip to main content

​
JavaScript SDK Installation

The Loyalty.lt JavaScript SDK provides a simple, powerful way to integrate loyalty features into your web applications. It supports both browser and Node.js environments with TypeScript definitions included.

​
Installation

  • npm
  • yarn
  • pnpm
  • CDN
npm install @loyalty-lt/javascript-sdk

​
Basic Setup

​
Initialize the SDK

import { LoyaltySDK } from '@loyalty-lt/javascript-sdk';

const sdk = new LoyaltySDK({
  apiKey: 'your_api_key',
  apiSecret: 'your_api_secret',
  environment: 'staging', // or 'production'
  locale: 'en' // or 'lt'
});

​
Configuration Options

​
apiKey
string
required
Your Loyalty.lt API key from the Partners Portal
​
apiSecret
string
required
Your Loyalty.lt API secret from the Partners Portal
​
environment
string
default:"staging"
API environment: staging or production
​
locale
string
default:"en"
Language for API responses: en (English) or lt (Lithuanian)
​
timeout
number
default:"10000"
Request timeout in milliseconds
​
retryAttempts
number
default:"3"
Number of retry attempts for failed requests
​
enableWebSocket
boolean
default:"false"
Enable real-time WebSocket connections

​
Quick Start Example

Here’s a complete example showing how to create a loyalty card and award points: 
import { LoyaltySDK } from '@loyalty-lt/javascript-sdk';

const sdk = new LoyaltySDK({
  apiKey: 'your_api_key',
  apiSecret: 'your_api_secret',
  environment: 'staging'
});

async function createLoyaltyProgram() {
  try {
    // Create a new loyalty card
    const card = await sdk.loyaltyCards.create({
      customer_email: 'customer@example.com',
      customer_name: 'John Doe',
      initial_points: 100
    });
    
    console.log('Created card:', card.id);
    
    // Award additional points
    const transaction = await sdk.points.award({
      card_id: card.id,
      points: 50,
      reason: 'Welcome bonus'
    });
    
    console.log('Awarded points:', transaction.points_awarded);
    
    // Get updated card details
    const updatedCard = await sdk.loyaltyCards.get(card.id);
    console.log('New balance:', updatedCard.points_balance);
    
  } catch (error) {
    console.error('Error:', error.message);
  }
}

createLoyaltyProgram();

​
API Reference

​
Loyalty Cards

const card = await sdk.loyaltyCards.create({
  customer_email: 'customer@example.com',
  customer_name: 'John Doe',
  customer_phone: '+1234567890',
  initial_points: 100
});

const card = await sdk.loyaltyCards.get('card_123456789');

const cards = await sdk.loyaltyCards.list({
  status: 'active',
  page: 1,
  limit: 20
});

const card = await sdk.loyaltyCards.update('card_123456789', {
  customer_name: 'John Smith',
  metadata: { preferred_contact: 'email' }
});

​
Points Management

const transaction = await sdk.points.award({
  card_id: 'card_123456789',
  points: 100,
  reason: 'Purchase reward',
  reference: 'order_123'
});

const transaction = await sdk.points.redeem({
  card_id: 'card_123456789',
  points: 50,
  reason: 'Discount applied',
  reference: 'discount_456'
});

const history = await sdk.points.getHistory('card_123456789', {
  type: 'all',
  page: 1,
  limit: 50
});

​
Offers & Coupons

const offer = await sdk.offers.create({
  title: '20% Off Next Purchase',
  description: 'Save 20% on your next order',
  discount_type: 'percentage',
  discount_value: 20,
  points_required: 100,
  expires_at: '2024-12-31T23:59:59Z'
});

const offers = await sdk.offers.list({
  status: 'active',
  customer_eligible: true
});

const coupon = await sdk.offers.redeem('offer_123456789', {
  card_id: 'card_123456789'
});

​
Error Handling

The SDK provides comprehensive error handling with typed error responses: 
try {
  const card = await sdk.loyaltyCards.get('invalid_id');
} catch (error) {
  if (error.code === 'CARD_NOT_FOUND') {
    console.log('Card not found');
  } else if (error.code === 'UNAUTHORIZED') {
    console.log('Check your API credentials');
  } else {
    console.log('Unexpected error:', error.message);
  }
}

​
Common Error Codes

Cause: Invalid API credentials Solution: Check your API key and secret
Cause: Loyalty card doesn’t exist Solution: Verify the card ID
Cause: Not enough points for redemption Solution: Check points balance before redemption
Cause: Too many requests Solution: Implement retry logic with backoff

​
Real-time Features

Enable WebSocket connections for real-time updates: 
const sdk = new LoyaltySDK({
  apiKey: 'your_api_key',
  apiSecret: 'your_api_secret',
  environment: 'staging',
  enableWebSocket: true
});

// Listen for real-time events
sdk.on('points.awarded', (event) => {
  console.log('Points awarded:', event.data.points);
  updateUI(event.data.card_id, event.data.new_balance);
});

sdk.on('offer.claimed', (event) => {
  console.log('Offer claimed:', event.data.offer_title);
  showNotification('Offer redeemed successfully!');
});

// Connect to real-time events
await sdk.connect();

​
Available Events

points.awarded

Triggered when points are awarded to a card

points.redeemed

Triggered when points are redeemed from a card

offer.claimed

Triggered when an offer is claimed by a customer

card.created

Triggered when a new loyalty card is created

​
Environment Variables

For security, store API credentials in environment variables:
  • .env
  • Node.js
  • Vite
  • Next.js
LOYALTY_API_KEY=your_api_key_here
LOYALTY_API_SECRET=your_api_secret_here
LOYALTY_ENVIRONMENT=staging

​
Framework Integrations

​
React Integration

For React applications, consider using our dedicated React hooks: 
npm install @loyalty-lt/react-sdk

import { LoyaltyProvider, useLoyaltyCard } from '@loyalty-lt/react-sdk';

function App() {
  return (
    <LoyaltyProvider apiKey="your_api_key">
      <LoyaltyCard customerId="customer_123" />
    </LoyaltyProvider>
  );
}

function LoyaltyCard({ customerId }) {
  const { card, loading, error, awardPoints } = useLoyaltyCard(customerId);
  
  if (loading) return <div>Loading...</div>;
  if (error) return <div>Error: {error.message}</div>;
  
  return (
    <div>
      <h3>Points Balance: {card.points_balance}</h3>
      <button onClick={() => awardPoints(10)}>
        Award 10 Points
      </button>
    </div>
  );
}

​
Vue.js Integration

Use Vue composables for reactive loyalty features: 
npm install @loyalty-lt/vue-sdk

<template>
  <div>
    <h3>Points: {{ card.points_balance }}</h3>
    <button @click="awardPoints(10)" :disabled="loading">
      Award Points
    </button>
  </div>
</template>

<script setup>
import { useLoyaltyCard } from '@loyalty-lt/vue-sdk';

const { card, loading, awardPoints } = useLoyaltyCard('customer_123');
</script>

​
Testing

Use the staging environment for development and testing: 
import { LoyaltySDK } from '@loyalty-lt/javascript-sdk';

describe('Loyalty SDK', () => {
  let sdk;
  
  beforeAll(() => {
    sdk = new LoyaltySDK({
      apiKey: 'test_api_key',
      apiSecret: 'test_api_secret',
      environment: 'staging'
    });
  });
  
  test('should create loyalty card', async () => {
    const card = await sdk.loyaltyCards.create({
      customer_email: 'test@example.com',
      customer_name: 'Test User'
    });
    
    expect(card.customer_email).toBe('test@example.com');
    expect(card.points_balance).toBe(0);
  });
  
  test('should award points', async () => {
    const card = await sdk.loyaltyCards.create({
      customer_email: 'test2@example.com',
      customer_name: 'Test User 2'
    });
    
    const transaction = await sdk.points.award({
      card_id: card.id,
      points: 100,
      reason: 'Test points'
    });
    
    expect(transaction.points_awarded).toBe(100);
  });
});

​
Performance Optimization

Request Caching

// Enable automatic caching
const sdk = new LoyaltySDK({
  apiKey: 'your_api_key',
  apiSecret: 'your_api_secret',
  cache: {
    enabled: true,
    ttl: 300000 // 5 minutes
  }
});

Request Batching

// Batch multiple operations
const results = await sdk.batch([
  sdk.loyaltyCards.get('card_1'),
  sdk.loyaltyCards.get('card_2'),
  sdk.points.getHistory('card_1')
]);

Connection Pooling

// Optimize for high-traffic applications
const sdk = new LoyaltySDK({
  apiKey: 'your_api_key',
  apiSecret: 'your_api_secret',
  pool: {
    maxConnections: 10,
    keepAlive: true
  }
});

Retry Logic

// Custom retry configuration
const sdk = new LoyaltySDK({
  apiKey: 'your_api_key',
  apiSecret: 'your_api_secret',
  retry: {
    attempts: 3,
    backoff: 'exponential',
    maxDelay: 5000
  }
});

​
Migration Guide

​
From v1.x to v2.x

  • Constructor now requires apiSecret parameter
  • createCard() method renamed to loyaltyCards.create()
  • awardPoints() method moved to points.award()
  • Error response format changed
  1. Update SDK version: npm install @loyalty-lt/javascript-sdk@latest
  2. Add API secret to configuration
  3. Update method calls to new namespace structure
  4. Update error handling for new format
  5. Test all integrations thoroughly
// v1.x (Old)
const sdk = new LoyaltySDK({ apiKey: 'key' });
const card = await sdk.createCard({ email: 'test@example.com' });
await sdk.awardPoints(card.id, 100);

// v2.x (New)
const sdk = new LoyaltySDK({ 
  apiKey: 'key', 
  apiSecret: 'secret' 
});
const card = await sdk.loyaltyCards.create({ 
  customer_email: 'test@example.com' 
});
await sdk.points.award({ card_id: card.id, points: 100 });

​
Next Steps

React SDK

Use React hooks and components for easier integration.

API Reference

Explore all available API endpoints and parameters.

Authentication

Learn about JWT tokens and advanced authentication.

WebSocket Events

Implement real-time features with WebSocket connections.

​
Support

Need help with the JavaScript SDK? Check out these resources:

​
Changelog

​
v2.1.0
Released December 2024

​
New Features

  • WebSocket support for real-time events
  • Request batching for improved performance
  • TypeScript definitions for better developer experience
  • Automatic retry logic with exponential backoff

​
Breaking Changes

  • Required apiSecret parameter in constructor
  • Reorganized API methods into namespaces
  • Updated error response format

​
Bug Fixes

  • Fixed memory leak in WebSocket connections
  • Improved error handling for network timeouts
  • Better handling of rate limit responses