Developer Docs

API Reference

Integrate Loyalty+ with your POS, e-commerce, or custom application

🔑Authentication

All POS API endpoints require an API key. Generate one from your Admin Portal under Billing → API Key.

X-API-Key: loy_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

📡POS Endpoints

Use X-API-Key header for authentication

POST/v1/pos/checkin

Award points to a customer

Request Body

{
  "phone": "+353123456789",
  "storeId": "cuid_optional",
  "amount": 25.5,
  "units": 3
}

Response

{
  "success": true,
  "customerId": "cuid_xxx",
  "pointsAwarded": 25,
  "totalPoints": 125,
  "rewardThreshold": 100,
  "rewardAvailable": true
}

• Use 'phone' or 'customerId' to identify customer
• Include 'amount' for SPEND mode, 'units' for UNIT mode

GET/v1/pos/customer/:identifier

Look up customer by phone or ID

Response

{
  "customerId": "cuid_xxx",
  "name": "John Doe",
  "phone": "+353123456789",
  "status": "ACTIVE",
  "totalPoints": 125,
  "rewardAvailable": true
}

GET/v1/pos/balance/:identifier

Quick balance check

Response

{
  "customerId": "cuid_xxx",
  "totalPoints": 125
}

POST/v1/pos/redeem

Redeem points for a reward

Request Body

{
  "phone": "+353123456789",
  "points": 100
}

Response

{
  "success": true,
  "redemptionId": "cuid_xxx",
  "pointsRedeemed": 100,
  "rewardTitle": "Free Coffee",
  "remainingPoints": 25
}

👥Customer Management

Use Bearer JWT token (admin login) for authentication

POST/v1/owner/customers

Create a new customer

Request Body

{
  "name": "John Doe",
  "phone": "+353123456789",
  "notes": "VIP customer",
  "initialPoints": 50
}

Response

{
  "success": true,
  "customer": {
    "id": "cuid_xxx",
    "name": "John Doe",
    "phone": "+353123456789",
    "totalPoints": 50
  }
}

GET/v1/owner/customers

List all customers (paginated)

Response

{
  "customers": [
    {
      "id": "...",
      "name": "...",
      "totalPoints": 125
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150
  }
}

• Query params: page, limit, search, statusFilter, sortBy, sortOrder

GET/v1/owner/customers/:id

Get customer details with points history

Response

{
  "customer": {
    "id": "...",
    "name": "...",
    "status": "ACTIVE"
  },
  "pointsHistory": [
    {
      "delta": 10,
      "reason": "Visit"
    }
  ],
  "totalPoints": 125
}

PATCH/v1/owner/customers/:id

Update customer (edit or lock/unlock)

Request Body

{
  "name": "Jane Doe",
  "phone": "+353987654321",
  "status": "BLOCKED"
}

Response

{
  "success": true,
  "customer": {
    "id": "...",
    "name": "Jane Doe",
    "status": "BLOCKED"
  }
}

• Set status to 'BLOCKED' to lock, 'ACTIVE' to unlock

POST/v1/owner/customers/:id/points

Add or deduct points with audit trail

Request Body

{
  "points": -50,
  "reason": "Refund for cancelled order"
}

Response

{
  "success": true,
  "newBalance": 75,
  "adjustment": -50
}

• Use positive number to add, negative to deduct

DELETE/v1/owner/customers/:id

Permanently delete a customer

Response

{
  "success": true,
  "message": "Customer deleted permanently"
}

💻Code Examples

cURL - Award Points

curl -X POST https://api.loyaltyplus.app/v1/pos/checkin \
  -H "Content-Type: application/json" \
  -H "X-API-Key: loy_your_api_key_here" \
  -d '{"phone": "+353123456789", "amount": 25.50}'

JavaScript - Create Customer

const response = await fetch('https://api.loyaltyplus.app/v1/owner/customers', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_JWT_TOKEN'
  },
  body: JSON.stringify({
    name: 'John Doe',
    phone: '+353123456789',
    initialPoints: 50
  })
});
const data = await response.json();

Ready to Integrate?

Go to Admin Portal Create Account