Frequently Asked Questions

What is Loyalty.lt and how does it work?

Which platforms and frameworks are supported?

What are the different API types and when should I use each?

How much does Loyalty.lt cost?

How do I get started with integration?

What's the difference between staging and production environments?

How do I migrate from staging to production?

To migrate from staging to production:

Update environment variables:

# Change from staging to production
LOYALTY_ENV=production
LOYALTY_API_URL=https://api.loyalty.lt

Update API endpoints in your code if hardcoded
Test thoroughly in staging first
Export/import data if needed (contact support for assistance)
Monitor closely after deployment

Important: Staging and production are separate environments. Data doesn’t automatically transfer between them.

Can I test with real customer data?

What authentication methods are supported?

Loyalty.lt supports multiple authentication methods:1. API Credentials (Recommended for most use cases)

// Shop API authentication
headers: {
  'Authorization': 'Bearer your_api_key',
  'Shop-ID': 'your_shop_id'
}

2. JWT Tokens (Partner API)

// Partner API authentication
headers: {
  'Authorization': 'Bearer jwt_token'
}

3. OAuth 2.0 (Advanced integrations)

Used for third-party app integrations
Requires approval from Loyalty.lt team
Supports various grant types

Security Best Practices:

Never expose API keys in client-side code
Use environment variables for credentials
Rotate keys regularly
Monitor API usage for anomalies

How do rate limits work?

Rate limits protect our API and ensure fair usage:Default Limits:

Shop API: 1,000 requests per hour per shop
Partner API: 5,000 requests per hour per partner
SDK API: 10,000 requests per hour per shop

Rate Limit Headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1609459200

When Rate Limited:

HTTP 429 status code returned
Retry after time provided in response
Implement exponential backoff in your code

Increasing Limits:

Contact support for higher limits
Enterprise plans include higher limits
Bulk operations use separate limits

How should I handle API errors?

Implement robust error handling for all API calls:HTTP Status Codes:

200: Success
400: Bad Request (validation errors)
401: Unauthorized (invalid credentials)
403: Forbidden (insufficient permissions)
404: Not Found (resource doesn’t exist)
409: Conflict (duplicate data)
429: Rate Limited
500: Server Error

Error Response Format:

{
  "error": {
    "code": "CUSTOMER_NOT_FOUND",
    "message": "Customer with ID 'xyz' not found",
    "details": {
      "customer_id": "xyz",
      "shop_id": "abc123"
    }
  }
}

Best Practices:

Always check HTTP status codes
Parse error messages for user feedback
Implement retry logic for transient errors
Log errors for debugging
Provide fallback behavior when possible

What data formats are supported?

Request/Response Format:

Primary: JSON (application/json)
Webhooks: JSON payload with signature verification
Exports: CSV, JSON, Excel formats

Date/Time Format:

ISO 8601: 2024-01-15T10:30:00Z
Date only: 2024-01-15
Timezone: UTC recommended, local timezone supported

Currencies:

ISO 4217 currency codes (USD, EUR, GBP, etc.)
Decimal precision: 2 decimal places
Format: Numeric (not string with symbols)

Example:

{
  "customer_id": "cust_123",
  "points": 150,
  "currency": "USD",
  "amount": 99.99,
  "created_at": "2024-01-15T10:30:00Z"
}

Why am I getting 'Invalid API credentials' errors?

This error indicates authentication issues. Check these common causes:1. Wrong API Key or Shop ID

# Verify your credentials in Partners Portal
https://partners.loyalty.lt/dashboard

2. Environment Mismatch

// Make sure you're using the right environment
const isProduction = process.env.NODE_ENV === 'production'
const apiKey = isProduction ? PROD_API_KEY : STAGING_API_KEY

3. Header Format Issues

// Correct format
headers: {
  'Authorization': 'Bearer ' + apiKey,  // Note the space after 'Bearer'
  'Shop-ID': shopId,
  'Content-Type': 'application/json'
}

4. Expired or Revoked Keys

Check if keys were recently regenerated
Verify account is active and in good standing
Contact support if keys appear corrupted

Debugging Steps:

Test credentials in our API explorer
Check for typos in key/ID
Verify environment URLs
Test with curl to isolate SDK issues

Points aren't being awarded to customers. What's wrong?

Several factors can prevent points from being awarded:1. Customer Not Found

// Ensure customer exists first
const customer = await loyalty.customers.get(customerId)
if (!customer) {
  // Create customer first
  await loyalty.customers.create(customerData)
}

2. Invalid Point Amount

// Points must be positive integers
const points = Math.max(1, Math.floor(calculatedPoints))

3. Duplicate Transaction Prevention

// Use unique order IDs to prevent duplicates
await loyalty.points.award({
  customer_id: customerId,
  points: points,
  reason: 'purchase',
  order_id: uniqueOrderId  // This prevents duplicates
})

4. Shop Configuration Issues

Check if points earning is enabled for your shop
Verify minimum order amounts
Review earning rate settings

Debugging:

Check API response for error details
Verify customer ID format and existence
Test with a known working customer
Review shop settings in Partners Portal

Webhooks aren't working. How do I fix them?

Webhook issues are common but usually easy to fix:1. Verify Webhook URL

Must be publicly accessible HTTPS URL
Should return 200 status code for valid requests
Test URL manually with tools like curl or Postman

2. Check Signature Verification

// Proper webhook verification
const crypto = require('crypto')

function verifyWebhook(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex')
  
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(`sha256=${expectedSignature}`)
  )
}

3. Common Response Issues

// Webhook handler should return 200
app.post('/webhook', (req, res) => {
  try {
    // Process webhook
    processWebhook(req.body)
    res.status(200).send('OK')  // Important!
  } catch (error) {
    res.status(500).send('Error')
  }
})

4. Debugging Steps

Check webhook logs in Partners Portal
Verify HTTPS certificate is valid
Test with ngrok for local development
Monitor server logs for errors
Use webhook testing tools

My integration is slow. How can I improve performance?

Several strategies can improve integration performance:1. Use Bulk Operations

// Instead of individual API calls
for (const customer of customers) {
  await loyalty.points.award(customer.id, points)
}

// Use bulk operations
await loyalty.points.bulkAward(customers.map(c => ({
  customer_id: c.id,
  points: points,
  reason: 'bulk_bonus'
})))

2. Implement Caching

// Cache customer data
const cache = new Map()

async function getCustomerPoints(customerId) {
  if (cache.has(customerId)) {
    return cache.get(customerId)
  }
  
  const balance = await loyalty.customers.getBalance(customerId)
  cache.set(customerId, balance, { ttl: 300 }) // 5 minute cache
  return balance
}

3. Use Asynchronous Processing

// Queue API calls for background processing
const queue = new Queue('loyalty-operations')

queue.add('award-points', {
  customerId,
  points,
  reason
})

4. Optimize Network Requests

Use HTTP/2 when available
Implement connection pooling
Reduce payload sizes
Batch related operations

5. Database Optimization

Index customer lookup fields
Cache frequently accessed data
Use read replicas for queries

How do I integrate with WooCommerce?

WooCommerce integration can be done in several ways:1. Official Plugin (Recommended)

Download from WordPress Plugin Directory
Easy setup through admin interface
Automatic point calculation and redemption
Built-in customer synchronization

2. Custom Integration

// Hook into WooCommerce events
add_action('woocommerce_order_status_completed', 'award_loyalty_points');

function award_loyalty_points($order_id) {
    $order = wc_get_order($order_id);
    $customer_id = $order->get_customer_id();
    $points = calculate_points($order->get_total());
    
    // Award points via API
    $loyalty = new LoyaltyClient($api_key, $shop_id);
    $loyalty->points()->award([
        'customer_id' => $customer_id,
        'points' => $points,
        'reason' => 'purchase',
        'order_id' => $order_id
    ]);
}

3. Configuration Steps

Install and activate the plugin
Configure API credentials
Set point earning rules
Configure redemption options
Test with a small order

Common Issues:

Ensure customer accounts are linked properly
Check point calculation rules
Verify webhook endpoints are working
Test redemption flow thoroughly

View Full WooCommerce Guide

Can customers use points across multiple stores?

Yes, Loyalty.lt supports multi-store point sharing:Partner-level Points

Points earned at any partner store
Can be redeemed at any partner store
Unified customer profiles across stores
Centralized tier progression

Configuration Required:

// Enable multi-store points in Partner API
await loyalty.partners.updateSettings({
  multi_store_points: true,
  point_sharing: 'full', // 'full', 'earning_only', 'redemption_only'
  unified_tiers: true
})

Customer Experience:

Single login across all stores
Combined points balance
Tier benefits at all locations
Unified transaction history

Implementation:

Use Partner API for multi-store setups
Implement customer SSO if needed
Configure store-specific earning rates
Set up cross-store redemption rules

Note: This feature requires Partner-level access and configuration.

How do I handle refunds and returns?

Refunds require careful handling of loyalty points:1. Automatic Point Deduction

// When processing a refund
await loyalty.points.deduct({
  customer_id: customerId,
  points: pointsToDeduct,
  reason: 'refund',
  order_id: originalOrderId,
  refund_id: refundId
})

2. Partial Refunds

// Calculate proportional point deduction
const originalPoints = 150
const originalAmount = 150.00
const refundAmount = 50.00
const pointsToDeduct = Math.floor((refundAmount / originalAmount) * originalPoints)

3. Grace Period Handling

// Check if points were already redeemed
const customerBalance = await loyalty.customers.getBalance(customerId)
if (customerBalance.points < pointsToDeduct) {
  // Handle insufficient points scenario
  // Options: partial deduction, negative balance, or block refund
}

Best Practices:

Deduct points immediately upon refund
Handle insufficient point scenarios gracefully
Maintain detailed refund logs
Consider grace periods for accidental purchases
Communicate point changes to customers

Configuration Options:

Allow negative point balances
Set maximum refund timeframes
Configure automatic vs manual point adjustments

How do I implement QR code scanning for loyalty cards?

QR code scanning can be implemented across platforms:JavaScript (Web)

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

// Initialize QR scanner
const scanner = LoyaltySDK.createQRScanner({
  onScan: (qrData) => {
    // Handle scanned loyalty card
    handleLoyaltyCardScan(qrData)
  },
  onError: (error) => {
    console.error('QR scan error:', error)
  }
})

async function handleLoyaltyCardScan(qrData) {
  try {
    const result = await loyalty.loyaltyCards.scan(qrData)
    const customer = result.customer
    
    // Show customer info or award points
    displayCustomerInfo(customer)
  } catch (error) {
    // Handle invalid QR code
    showError('Invalid loyalty card')
  }
}

React Native

import { Camera } from 'expo-camera'
import { LoyaltySDK } from '@loyalty-lt/react-native-sdk'

function QRScanner() {
  const handleBarCodeScanned = async ({ data }) => {
    try {
      const result = await LoyaltySDK.scanLoyaltyCard(data)
      // Handle successful scan
    } catch (error) {
      // Handle scan error
    }
  }

  return (
    <Camera
      onBarCodeScanned={handleBarCodeScanned}
      barCodeScannerSettings={{
        barCodeTypes: ['qr'],
      }}
    />
  )
}

Native Mobile Integration:

iOS: Use AVFoundation for camera access
Android: Use Camera2 API or CameraX
Consider using existing QR libraries like ZXing

QR Code Format:

Contains encrypted customer ID and validation data
Includes expiration timestamp
Has built-in error correction

Can I customize the loyalty widget appearance?

Yes, loyalty widgets are highly customizable:Theme Configuration

LoyaltySDK.init({
  apiKey: 'your_api_key',
  shopId: 'your_shop_id',
  theme: {
    primaryColor: '#007bff',
    secondaryColor: '#6c757d',
    backgroundColor: '#ffffff',
    textColor: '#333333',
    borderRadius: '8px',
    fontFamily: 'Arial, sans-serif'
  }
})

CSS Customization

/* Override widget styles */
.loyalty-widget {
  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
  border-radius: 12px;
  box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1);
}

.loyalty-points {
  font-size: 24px;
  font-weight: bold;
  color: #ffffff;
}

.loyalty-tier {
  background: rgba(255, 255, 255, 0.2);
  padding: 4px 8px;
  border-radius: 4px;
}

Component Customization

// Custom loyalty card component
function CustomLoyaltyCard({ customer }) {
  return (
    <div className="custom-loyalty-card">
      <div className="card-header">
        <h3>{customer.firstName}'s Rewards</h3>
      </div>
      <div className="card-body">
        <div className="points-display">
          {customer.points} Points
        </div>
        <div className="tier-display">
          {customer.tier} Member
        </div>
      </div>
    </div>
  )
}

Available Customization Options:

Colors and branding
Font styles and sizes
Layout and positioning
Button styles and text
Animation effects
Responsive behavior

How do I handle offline scenarios in mobile apps?

Offline support is crucial for mobile loyalty apps:1. Local Data Storage

// Store customer data locally
import AsyncStorage from '@react-native-async-storage/async-storage'

class OfflineLoyalty {
  async cacheCustomerData(customerId, data) {
    await AsyncStorage.setItem(
      `loyalty_customer_${customerId}`,
      JSON.stringify({
        ...data,
        cached_at: new Date().toISOString()
      })
    )
  }
  
  async getCachedCustomerData(customerId) {
    const cached = await AsyncStorage.getItem(`loyalty_customer_${customerId}`)
    if (cached) {
      const data = JSON.parse(cached)
      // Check if cache is still valid (e.g., less than 1 hour old)
      const isValid = new Date() - new Date(data.cached_at) < 3600000
      return isValid ? data : null
    }
    return null
  }
}

2. Queue Offline Actions

// Queue actions for when connection is restored
class ActionQueue {
  constructor() {
    this.queue = []
  }
  
  addAction(action) {
    this.queue.push({
      ...action,
      timestamp: new Date().toISOString()
    })
    this.saveQueue()
  }
  
  async processQueue() {
    if (!this.isOnline()) return
    
    for (const action of this.queue) {
      try {
        await this.executeAction(action)
        this.removeFromQueue(action)
      } catch (error) {
        // Keep in queue for retry
        console.log('Action failed, will retry:', error)
      }
    }
  }
}

3. Sync Strategy

// Implement smart sync when connection restored
NetInfo.addEventListener(state => {
  if (state.isConnected) {
    syncOfflineData()
  }
})

async function syncOfflineData() {
  // Process queued actions
  await actionQueue.processQueue()
  
  // Refresh customer data
  await refreshCustomerData()
  
  // Update local cache
  await updateLocalCache()
}

Best Practices:

Cache essential data for offline viewing
Queue actions for later sync
Show clear offline indicators
Handle conflicts gracefully
Implement retry mechanisms

How do I get technical support?

Where can I find code examples and tutorials?

How do I report bugs or request features?

Developer Guides

Partner Guides

Integration Guides

Frequently Asked Questions

General Questions

Integration Questions

Technical Questions

Common Issues

E-commerce Specific

Mobile & SDK Questions

Support & Contact

Still Need Help?

Technical Support

Community Forum

API Reference

Contact Sales

Developer Guides

Partner Guides

Integration Guides

​Frequently Asked Questions

​General Questions

​Integration Questions

​Technical Questions

​Common Issues

​E-commerce Specific

​Mobile & SDK Questions

​Support & Contact

​Still Need Help?

Technical Support

Community Forum

API Reference

Contact Sales

Frequently Asked Questions

General Questions

Integration Questions

Technical Questions

Common Issues

E-commerce Specific

Mobile & SDK Questions

Support & Contact

Still Need Help?