curl -X POST 'https://staging-api.loyalty.lt/api/points/award' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: your_api_key_here' \
  -H 'X-API-Secret: your_api_secret_here' \
  -d '{
    "card_id": "card_123456789",
    "points": 50,
    "reason": "Purchase reward",
    "reference": "order_123"
  }'

{
  "success": true,
  "data": {
    "id": "card_123456789",
    "customer_email": "customer@example.com",
    "customer_name": "John Doe",
    "points_balance": 100,
    "card_number": "LC001234567890",
    "status": "active",
    "created_at": "2024-12-27T10:30:00Z"
  }
}

​
Quick Start Guide

This guide will help you integrate with Loyalty.lt APIs and start building loyalty features into your application within minutes.

​
Prerequisites

Before you begin, ensure you have:
  • A Loyalty.lt partner account
  • API credentials (API Key and Secret)
  • Basic knowledge of REST APIs

​
Step 1: Choose Your Integration Path

Select the most appropriate API layer for your needs:
Best for: Direct store integration, simple loyalty features
  • Basic loyalty card management
  • Points earning and redemption
  • Offer creation and redemption
  • Customer management
Base URL: https://staging-api.loyalty.lt/api/

​
Step 2: Authentication Setup

All Loyalty.lt APIs use API credentials for authentication. You’ll need both an API Key and API Secret.
1

Get your credentials

Visit the Partners Portal and navigate to API settings to generate your credentials.
Keep your API credentials secure. Never expose them in client-side code.
2

Test authentication

Make a test request to verify your credentials work:
cURL
curl -X GET 'https://staging-api.loyalty.lt/api/health' \
  -H 'X-API-Key: your_api_key_here' \
  -H 'X-API-Secret: your_api_secret_here'
You should receive a 200 OK response with system status information.

​
Step 3: Make Your First API Call

Let’s create a simple loyalty card to test the integration: 
const apiKey = 'your_api_key_here';
const apiSecret = 'your_api_secret_here';

const response = await fetch('https://staging-api.loyalty.lt/api/loyalty-cards', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': apiKey,
    'X-API-Secret': apiSecret
  },
  body: JSON.stringify({
    customer_email: 'customer@example.com',
    customer_name: 'John Doe',
    initial_points: 100
  })
});

const card = await response.json();
console.log('Created loyalty card:', card);

{
  "success": true,
  "data": {
    "id": "card_123456789",
    "customer_email": "customer@example.com",
    "customer_name": "John Doe",
    "points_balance": 100,
    "card_number": "LC001234567890",
    "status": "active",
    "created_at": "2024-12-27T10:30:00Z"
  }
}

​
Step 4: Award Points

Now let’s award some points to the loyalty card we just created: 
curl -X POST 'https://staging-api.loyalty.lt/api/points/award' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: your_api_key_here' \
  -H 'X-API-Secret: your_api_secret_here' \
  -d '{
    "card_id": "card_123456789",
    "points": 50,
    "reason": "Purchase reward",
    "reference": "order_123"
  }'

{
  "success": true,
  "data": {
    "transaction_id": "txn_987654321",
    "card_id": "card_123456789",
    "points_awarded": 50,
    "new_balance": 150,
    "reason": "Purchase reward",
    "created_at": "2024-12-27T10:35:00Z"
  }
}

​
Step 5: Check Points Balance

Verify the points were awarded correctly: 
curl -X GET 'https://staging-api.loyalty.lt/api/loyalty-cards/card_123456789' \
  -H 'X-API-Key: your_api_key_here' \
  -H 'X-API-Secret: your_api_secret_here'

{
  "success": true,
  "data": {
    "id": "card_123456789",
    "customer_email": "customer@example.com",
    "customer_name": "John Doe",
    "points_balance": 150,
    "card_number": "LC001234567890",
    "status": "active",
    "last_activity": "2024-12-27T10:35:00Z",
    "created_at": "2024-12-27T10:30:00Z"
  }
}

​
Next Steps

Explore Shop APIs

Learn about all available shop API endpoints for loyalty card management.

SDK Integration

Use our SDKs for easier integration with built-in error handling and utilities.

Partner Portal

Set up analytics dashboards and manage multiple shops.

E-commerce Plugins

Integrate with popular e-commerce platforms using our plugins.

​
Common Integration Patterns

​
Error Handling

Always implement proper error handling in your integration. All API endpoints return standardized error responses.

​
Common HTTP Status Codes

StatusDescriptionAction
200SuccessContinue processing
400Bad RequestCheck request parameters
401UnauthorizedVerify API credentials
403ForbiddenCheck permissions
429Rate LimitedImplement retry logic
500Server ErrorContact support

​
Error Response Format

{
  "success": false,
  "error": {
    "code": "INVALID_PARAMETERS",
    "message": "The customer_email field is required",
    "details": {
      "field": "customer_email",
      "rule": "required"
    }
  }
}

​
Rate Limiting

All API endpoints are subject to rate limiting. Monitor the response headers for rate limit information.

​
Rate Limit Headers

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

​
Handling Rate Limits

Implement exponential backoff when you receive a 429 status code: 
async function makeAPICall(url, options, retryCount = 0) {
  const response = await fetch(url, options);
  
  if (response.status === 429 && retryCount < 3) {
    const waitTime = Math.pow(2, retryCount) * 1000; // 1s, 2s, 4s
    await new Promise(resolve => setTimeout(resolve, waitTime));
    return makeAPICall(url, options, retryCount + 1);
  }
  
  return response;
}

​
Need Help?

If you encounter any issues during integration, our support team is here to help.
Ready to dive deeper? Choose your next step:

Shop API Reference

SDK Documentation

Partner Portal Guide