Server SDK Overview

The useLoyalty Server SDK provides a typed client and RESTful API for integrating gamification features into your application. Use it to manage members, award points, track quests, and create engaging loyalty experiences.

Installation

npm install @useloyalty/sdk
# or
pnpm add @useloyalty/sdk

Quick Start

Using the SDK Client (Recommended)

import { UseLoyaltyClient } from "@useloyalty/sdk";

const useLoyalty = new UseLoyaltyClient({
  publicKey: process.env.USELOYALTY_PUBLIC_KEY!,
  privateKey: process.env.USELOYALTY_PRIVATE_KEY!,
});

// Award points
await useLoyalty.members.awardPoints("user_123", {
  amount: 100,
  description: "Welcome bonus",
});

// Track events
await useLoyalty.events.track("user_123", {
  event: "purchase",
  properties: { amount: 99.99 },
});

// Generate widget auth
const auth = useLoyalty.generateWidgetAuth("user_123");

Using Raw REST API

const response = await fetch(
  "https://app.useloyalty.app/api/v1/members/user_123/points",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer sk_your_private_key",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      amount: 100,
      description: "Welcome bonus",
    }),
  },
);

Base URL

https://app.useloyalty.app/api/v1

Key Features

Members

Create and manage member profiles, track points balances

Points

Award, deduct, and query point transactions

Quests

Define challenges and track completion progress

Events

Track custom events that trigger automated quests

Referrals

Build viral growth with referral programs

Badges

Award achievements and milestones

Promo Codes

Redeem promotional codes for points or rewards

API Endpoints Summary

Resource	Endpoints
Members	`POST /members`, `GET /members`, `GET /members/:id`, `PATCH /members/:id`, `DELETE /members/:id`
Points	`GET /members/:id/points`, `POST /members/:id/points`
Badges	`GET /members/:id/badges`, `POST /members/:id/badges`, `DELETE /members/:id/badges`
Quests	`POST /quests/:id/complete`, `POST /quests/:id/progress`
Events	`POST /events`
Referrals	`POST /referrals/apply`, `POST /referrals/convert`, `GET /referrals/stats/:id`
Promo Codes	`POST /promo-codes/redeem`

Response Format

All API responses follow a consistent JSON format:

{
  "success": true,
  "data": { ... }
}

Error responses include a message:

{
  "error": "Invalid API key",
  "message": "The provided API key is not valid"
}

HTTP Status Codes

Code	Description
`200`	Success
`201`	Created
`400`	Bad request / Validation error
`401`	Unauthorized / Invalid API key
`404`	Resource not found
`409`	Conflict (e.g., duplicate resource)
`500`	Server error

Rate Limiting

API requests are rate limited per API key. Current limits:

1000 requests/minute for standard operations
100 requests/minute for bulk operations

Rate limit headers are included in responses:

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