REST API

API Reference

Programmatic access to your Loyalty Loop loyalty platform. Build POS integrations, mobile apps, or automate your loyalty workflows.

RESTful · JSON responses

Bearer token authentication

Webhook event subscriptions

10

Endpoints

4

Resources

4

Webhook Events

v1

Version

Professional or Enterprise Plan Required

API access is available on Professional and Enterprise plans. Upgrade your plan →

Base URL

URL

http://loyaltyloop.in/api/v1

Postman Collection

10 pre-built requests — import and start testing in seconds

Download

10

Requests

4

Folders

v2.1

Format

How to import

1 Download the collection using the button above
2 Open Postman → click Import (top-left)
3 Drag the .json file into the import window
4 Open the collection → go to the Variables tab
5 Set base_url and your api_key
6 Path variables (customer ID, QR code) are set per-request in the Path Variables tab

Collection Variables

Variable	Default	Description
base_url	http://loyaltyloop.in	Change to `http://localhost` for local dev
api_key	ll_YOUR_API_KEY	Your API key from Settings → API Access

Authentication

All requests require a Bearer token in the Authorization header.

Get Your API Key

1 Log in to your account
2 Upgrade to Professional or Enterprise (if needed)
3 Go to Settings → API Access
4 Copy and store your API key securely

cURLExample Request

curl -X GET \
  -H "Authorization: Bearer ll_xxxxxxxxxxxxxxxxxxxxxxxx" \
  http://loyaltyloop.in/api/v1/customers

Keep Your Key Secret

Never expose your API key in client-side code or commit it to version control.

Rate Limits

Requests are throttled per API key to ensure reliability for all users.

Professional

1,000

requests / hour

Enterprise

Custom

contact us for higher limits

Response Headers

HTTP

X-RateLimit-Limit:     1000
X-RateLimit-Remaining: 995
X-RateLimit-Reset:     1678886400

Error Handling

Standard HTTP status codes. All errors return a JSON body.

200 OK — Success

201 Created — Resource created

400 Bad Request — Invalid parameters

401 Unauthorized — Invalid / missing key

403 Forbidden — Plan restriction

404 Not Found — Resource missing

429 Too Many Requests — Rate limit

500 Server Error — Contact support

Error Response Format

JSON

{
  "error":   true,
  "message": "Customer not found"
}

List Customers

GET/customers

Retrieve a paginated list of all customers in your loyalty program.

Parameter	Type	Description
page	integer	Page number (default: 1)
limit	integer	Results per page (default: 50 · max: 100)

cURLRequest

curl -X GET \
  -H "Authorization: Bearer YOUR_API_KEY" \
  "http://loyaltyloop.in/api/v1/customers?page=1&limit=50"

JSONResponse 200

{
  "data": [
    {
      "id":             1,
      "name":           "John Doe",
      "email":          "john@example.com",
      "phone":          "1234567890",
      "qr_code":        "CUS12AB34CD56",
      "current_stamps": 8,
      "total_visits":   15,
      "joined_at":      "2026-01-15 10:30:00",
      "last_visit":     "2026-03-10 14:20:00"
    }
  ],
  "pagination": {
    "page":  1,
    "limit": 50,
    "total": 150,
    "pages": 3
  }
}

Get Customer

GET/customers/{id}

Retrieve detailed information about a specific customer including their recent transactions.

cURLRequest

curl -X GET \
  -H "Authorization: Bearer YOUR_API_KEY" \
  "http://loyaltyloop.in/api/v1/customers/1"

JSONResponse 200

{
  "data": {
    "id":             1,
    "name":           "John Doe",
    "email":          "john@example.com",
    "phone":          "1234567890",
    "qr_code":        "CUS12AB34CD56",
    "current_stamps": 8,
    "total_visits":   15,
    "joined_at":      "2026-01-15 10:30:00",
    "last_visit":     "2026-03-10 14:20:00",
    "transactions": [
      {
        "id":               45,
        "transaction_type": "stamp_add",
        "stamps_added":     2,
        "created_at":       "2026-03-10 14:20:00"
      }
    ]
  }
}

Get by QR Code

GET/customers/qr/{qr_code}

Look up a customer by their QR code. Use this when scanning a loyalty card before adding stamps.

QR Scan Flow

Scan the customer's QR code → use the qr_code value here to fetch their loyalty status, then call the stamp endpoint.

Parameter	Type	Description
qr_code	string	The customer QR code value (e.g. CUS12AB34CD56)

cURLRequest

curl -X GET \
  -H "Authorization: Bearer YOUR_API_KEY" \
  "http://loyaltyloop.in/api/v1/customers/qr/CUS12AB34CD56"

JSONResponse 200

{
  "data": {
    "id":               1,
    "name":             "John Doe",
    "qr_code":          "CUS12AB34CD56",
    "current_stamps":   5,
    "rewards_earned":   1,
    "rewards_redeemed": 1,
    "total_visits":     10,
    "last_visit":       "2026-03-18 14:00:00"
  }
}

Create Customer

POST/customers

Create a new customer in your loyalty program. Returns the created customer with their unique QR code.

Field	Type	Required	Description
name	string	Required	Customer's full name
phone	string	Required	Customer's phone number
email	string	Optional	Customer's email address

cURLRequest

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Jane Smith","phone":"9876543210","email":"jane@example.com"}' \
  "http://loyaltyloop.in/api/v1/customers"

JSONResponse 201

{
  "data": {
    "id":             151,
    "name":           "Jane Smith",
    "email":          "jane@example.com",
    "phone":          "9876543210",
    "qr_code":        "CUSAB12CD34EF56",
    "current_stamps": 0,
    "total_visits":   0,
    "joined_at":      "2026-03-13 15:45:00"
  }
}

Add Stamps by ID

POST/customers/{id}/stamps

Add stamps to a customer by their numeric ID and record a visit.

Field	Type	Description
stamps	integer	Number of stamps to add (1–10)

cURLRequest

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"stamps":2}' \
  "http://loyaltyloop.in/api/v1/customers/1/stamps"

JSONResponse 200

{
  "data": {
    "id":             1,
    "name":           "John Doe",
    "current_stamps": 10,
    "total_visits":   16,
    "last_visit":      "2026-03-13 15:50:00"
  }
}

Add Stamps by QR Code

POST/customers/qr/{qr_code}/stamps

Add stamps using a QR code — the primary scan-and-stamp flow for POS integrations. When stamps reach the program threshold the reward is issued and current_stamps resets to 0.

Recommended for POS / Scanner Integrations

Prefer this endpoint over /customers/{id}/stamps — QR codes are immediately available after a scan.

Field	Type	Description
stamps	integer	Stamps to add (1–10 · default: 1)

cURLRequest

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"stamps":1}' \
  "http://loyaltyloop.in/api/v1/customers/qr/CUS12AB34CD56/stamps"

JSONResponse — Stamp Added

{
  "data": {
    "id":                  1,
    "name":                "John Doe",
    "qr_code":             "CUS12AB34CD56",
    "current_stamps":      6,
    "rewards_earned":      1,
    "total_visits":        11,
    "reward_earned":       false,
    "stamps_required":     8,
    "reward_description": "Free coffee"
  }
}

JSONResponse — Reward Earned

{
  "data": {
    "id":                  1,
    "name":                "John Doe",
    "qr_code":             "CUS12AB34CD56",
    "current_stamps":      0,  // reset after reward
    "rewards_earned":      2,
    "total_visits":        11,
    "reward_earned":       true,
    "stamps_required":     8,
    "reward_description": "Free coffee"
  }
}

When reward_earned is true, show a reward notification and prompt staff to redeem via /redeem.

Get Analytics

GET/analytics

Get an aggregated analytics summary for your loyalty program over a specified period.

Parameter	Type	Description
days	integer	Days to analyze (default: 30 · max: 365)

cURLRequest

curl -X GET \
  -H "Authorization: Bearer YOUR_API_KEY" \
  "http://loyaltyloop.in/api/v1/analytics?days=30"

JSONResponse 200

{
  "data": {
    "total_customers":    150,
    "new_customers":       25,
    "active_customers":    80,
    "total_visits":        450,
    "total_stamps":         900,
    "total_redemptions":   35,
    "growth_rate":          12.5,
    "avg_stamps_per_visit": 2.0,
    "period_days":          30
  }
}

List Webhooks

GET/webhooks

List all registered webhook endpoints for your business.

cURLRequest

curl -X GET \
  -H "Authorization: Bearer YOUR_API_KEY" \
  "http://loyaltyloop.in/api/v1/webhooks"

JSONResponse 200

{
  "data": [
    {
      "id":         1,
      "url":        "https://yoursite.com/webhook",
      "events":    ["customer.created", "stamp.added", "reward.redeemed"],
      "is_active": true,
      "created_at": "2026-03-01 10:00:00"
    }
  ]
}

Register Webhook

POST/webhooks

Register a webhook URL to receive real-time event notifications. Returns a secret for signature verification — store it securely, it is shown only once.

Field	Type	Required	Description
url	string	Required	Your publicly accessible HTTPS endpoint
events	array	Required	One or more event names to subscribe to

Available Events

customer.createdNew customer joined

stamp.addedStamps added to a customer

reward.redeemedCustomer redeemed a reward

customer.updatedCustomer profile updated

cURLRequest

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://yoursite.com/hook","events":["customer.created","stamp.added"]}' \
  "http://loyaltyloop.in/api/v1/webhooks"

JSONResponse 201

{
  "success": true,
  "data": {
    "id":     2,
    "url":    "https://yoursite.com/hook",
    "events": ["customer.created", "stamp.added"],
    "secret": "whsec_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  }
}

Delete Webhook

DELETE/webhooks/{id}

Delete a webhook by its ID. The endpoint will immediately stop receiving events.

cURLRequest

curl -X DELETE \
  -H "Authorization: Bearer YOUR_API_KEY" \
  "http://loyaltyloop.in/api/v1/webhooks/2"

JSONResponse 200

{
  "success": true,
  "message": "Webhook deleted"
}

Code Examples

JavaScript

const axios = require('axios');

const API_KEY  = 'll_YOUR_API_KEY';
const BASE_URL = 'http://loyaltyloop.in/api/v1';
const headers  = { Authorization: `Bearer ${API_KEY}` };

// List customers
async function listCustomers() {
  const res = await axios.get(`${BASE_URL}/customers`, { headers });
  return res.data;
}

// Scan-and-stamp flow (recommended for POS)
async function addStampsByQR(qrCode, stamps = 1) {
  const res = await axios.post(
    `${BASE_URL}/customers/qr/${qrCode}/stamps`,
    { stamps },
    { headers }
  );
  const data = res.data.data;
  if (data.reward_earned) {
    console.log(`🎉 Reward earned: ${data.reward_description}`);
  }
  return data;
}

// Create a customer
async function createCustomer(name, phone, email) {
  const res = await axios.post(`${BASE_URL}/customers`, { name, phone, email }, { headers });
  return res.data.data;
}

SDKs & Libraries

Official SDKs are in development. For now, use any HTTP client with the code examples above.

M

Node.js SDK

Soon

npm install @loyaltyloop/sdk

P

Python SDK

Soon

pip install loyaltyloop

PHP

PHP SDK

Soon

composer require loyaltyloop/sdk

TS

TypeScript SDK

Soon

npm install @loyaltyloop/ts-sdk

Built a community SDK? Let us know and we'll feature it here.

API Reference

Postman Collection

Authentication

Rate Limits

Error Handling

Customers

List Customers

Get Customer

Get by QR Code

Create Customer

Add Stamps by ID

Add Stamps by QR Code

Analytics

Get Analytics

Webhooks

List Webhooks

Register Webhook

Delete Webhook

Code Examples

SDKs & Libraries

Need Help?