Skip to main content

Basic Usage

This guide covers the most common SDK operations for Shop API integration.

Initialization

import { LoyaltySDK } from '@loyaltylt/sdk';

const sdk = new LoyaltySDK({
  apiKey: 'lty_your_api_key',
  apiSecret: 'your_api_secret',
  environment: 'production',
  locale: 'lt',
  debug: true // Enable for development
});

Shops

List Partner Shops

// Get all shops
const shops = await sdk.getShops();
console.log(shops.data); // Array of shops
console.log(shops.meta); // Pagination info

// Filter shops
const activeShops = await sdk.getShops({ 
  is_active: true,
  is_virtual: false 
});

Get Single Shop

const shop = await sdk.getShop(4);
console.log(shop.name, shop.address);

Loyalty Cards

List Cards

// Get all partner's loyalty cards
const cards = await sdk.getLoyaltyCards();

// Filter by card number
const card = await sdk.getLoyaltyCards({ 
  card_number: '123-456-789' 
});

Get Card Details

const card = await sdk.getLoyaltyCard(123);
console.log(card.card_number);
console.log(card.points_balance);
console.log(card.user); // Customer info

Points & Transactions

Create Transaction (Award Points)

const transaction = await sdk.createTransaction({
  card_id: 123,
  amount: 50.00,        // Purchase amount in EUR
  points: 50,           // Points to award
  type: 'earn',
  description: 'Purchase reward',
  reference: 'ORDER-12345'
});

console.log('Transaction ID:', transaction.id);
console.log('Points awarded:', transaction.points);

Get Points Balance

const balance = await sdk.getPointsBalance(123);
console.log('Current points:', balance.current_points);
console.log('Lifetime earned:', balance.total_earned);

Transaction History

const history = await sdk.getPointsTransactions({
  card_id: 123,
  type: 'earn',
  page: 1,
  per_page: 20
});

Offers

List Available Offers

const offers = await sdk.getOffers();

// Filter by category
const diningOffers = await sdk.getOffers({ 
  category: 'dining',
  is_active: true 
});
const featured = await sdk.getFeaturedOffers();

Claim Offer

const coupon = await sdk.claimOffer(offerId, shopId);
console.log('Coupon code:', coupon.code);
console.log('Expires:', coupon.expires_at);

Coupons

List Customer Coupons

const coupons = await sdk.getCoupons({
  status: 'active'
});

Redeem Coupon

const result = await sdk.redeemCoupon(couponId, {
  amount: 25.00,
  reference: 'ORDER-12345'
});

Error Handling

The SDK uses custom error types for better error handling:
import { LoyaltySDKError } from '@loyaltylt/sdk';

try {
  const result = await sdk.getLoyaltyCardInfo({ card_number: 'INVALID' });
} catch (error) {
  if (error instanceof LoyaltySDKError) {
    console.error('Error code:', error.code);
    console.error('Message:', error.message);
    console.error('Status:', error.status);
    
    switch (error.code) {
      case 'CARD_NOT_FOUND':
        alert('Loyalty card not found');
        break;
      case 'AUTH_FAILED':
        alert('Authentication failed');
        break;
      default:
        alert('An error occurred: ' + error.message);
    }
  }
}

Points Calculator

The SDK includes utility functions for points calculations:
import { 
  calculateAmountFromPoints,
  calculatePointsFromAmount,
  calculateFinalAmount,
  calculateMaxRedeemablePoints,
  validatePointsRedemption
} from '@loyaltylt/sdk';

// Points rules from backend
const pointsRules = {
  points_per_currency: 10,           // 10 points per 1 EUR
  currency_amount: 1,
  points_redemption_enabled: true,
  points_per_currency_redemption: 100, // 100 points = 1 EUR
  currency_amount_redemption: 1,
  min_points_for_redemption: 100,
  max_points_per_redemption: 5000
};

// Calculate discount from points
const discount = calculateAmountFromPoints(500, pointsRules);
// Result: 5.00 (500 points = 5 EUR)

// Calculate points earned from purchase
const pointsEarned = calculatePointsFromAmount(25.00, pointsRules);
// Result: 250 (25 EUR = 250 points)

// Calculate final amount after points discount
const finalAmount = calculateFinalAmount(50.00, 500, pointsRules);
// Result: 45.00 (50 EUR - 5 EUR discount)

// Get max redeemable points for amount
const maxPoints = calculateMaxRedeemablePoints(30.00, 5000, pointsRules);
// Result: 3000 (enough to cover 30 EUR)

// Validate redemption
const validation = validatePointsRedemption(500, 1000, pointsRules);
// Result: { isValid: true }

TypeScript Support

The SDK is written in TypeScript and includes full type definitions:
import { 
  LoyaltySDK,
  Shop,
  LoyaltyCard,
  PointsTransaction,
  Offer,
  PaginatedResponse,
  LoyaltySDKError,
  PointsRules
} from '@loyaltylt/sdk';

// Fully typed responses
const shops: PaginatedResponse<Shop> = await sdk.getShops();
const card: LoyaltyCard = await sdk.getLoyaltyCard(123);

Debug Mode

Enable debug mode to see detailed request/response logs:
const sdk = new LoyaltySDK({
  apiKey: 'lty_...',
  apiSecret: '...',
  debug: true
});

// Console output:
// [SDK] GET https://api.loyalty.lt/lt/shop/shops
// [SDK] Response: {"success":true,"data":[...],"meta":{...}}

Next Steps