Analytics

The Analytics API gives you programmatic access to program-level metrics and per-member activity logs. Use it to build internal dashboards, trigger alerts, or feed data into your BI tooling.

Program Overview

Fetch aggregate metrics for your loyalty program over a date range.

GET /api/v1/analytics/overview

Query Parameters

Parameter	Type	Description
`startDate`	string	ISO 8601 start date (default: 30 days ago)
`endDate`	string	ISO 8601 end date (default: now)

SDK

// Last 30 days (default)
const overview = await useLoyalty.analytics.getOverview();

// Custom range
const overview = await useLoyalty.analytics.getOverview({
  startDate: '2024-01-01',
  endDate: '2024-01-31',
});

Response

{
  "period": {
    "start": "2024-01-01T00:00:00Z",
    "end": "2024-01-31T23:59:59Z"
  },
  "totalMembers": 3842,
  "activeMembers": 1205,
  "pointsIssued": 485200,
  "pointsRedeemed": 142000,
  "totalRedemptions": 284,
  "totalEvents": 12450
}

Field	Description
`totalMembers`	All members registered as of `endDate`
`activeMembers`	Members with at least one event in the period
`pointsIssued`	Total points awarded in the period
`pointsRedeemed`	Total points spent on rewards in the period
`totalRedemptions`	Number of reward redemptions
`totalEvents`	Number of tracked events

Member Activity Log

Fetch the points transaction history for a specific member.

GET /api/v1/analytics/members/:externalId/activity

Query Parameters

Parameter	Type	Default	Description
`limit`	number	20	Results per page
`offset`	number	0	Pagination offset
`cursor`	string	—	Cursor for cursor-based pagination

SDK

const { data: activity, hasMore, nextCursor } = await useLoyalty.analytics.getMemberActivity(
  'user_123',
  { limit: 20 }
);

Response

{
  "data": [
    {
      "id": "txn_abc",
      "type": "AWARD",
      "amount": 100,
      "balance": 1600,
      "description": "Order #5521 bonus",
      "source": "shopify",
      "idempotencyKey": "order-5521-points",
      "expiresAt": null,
      "createdAt": "2024-01-20T10:30:00Z"
    },
    {
      "id": "txn_def",
      "type": "REDEMPTION",
      "amount": -500,
      "balance": 1100,
      "description": "Redeemed: 10% Off Coupon",
      "source": null,
      "idempotencyKey": null,
      "expiresAt": null,
      "createdAt": "2024-01-19T15:00:00Z"
    }
  ],
  "total": 48,
  "hasMore": true,
  "nextCursor": "cursor_xyz"
}

Code Examples

Weekly Report Cron

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

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

export async function weeklyReport() {
  const end = new Date();
  const start = new Date(end);
  start.setDate(start.getDate() - 7);

  const overview = await useLoyalty.analytics.getOverview({
    startDate: start.toISOString(),
    endDate: end.toISOString(),
  });

  const redemptionRate = overview.pointsRedeemed / overview.pointsIssued;

  return {
    ...overview,
    redemptionRate: `${(redemptionRate * 100).toFixed(1)}%`,
    engagementRate: `${((overview.activeMembers / overview.totalMembers) * 100).toFixed(1)}%`,
  };
}

Paginate Full Activity for a Member

async function getAllMemberActivity(externalId: string) {
  const all = [];
  let cursor: string | undefined;

  do {
    const page = await useLoyalty.analytics.getMemberActivity(externalId, {
      limit: 100,
      cursor,
    });
    all.push(...page.data);
    cursor = page.nextCursor;
  } while (page.hasMore);

  return all;
}

For real-time event streams or high-volume analytics pipelines, use Webhooks to push events to your own data warehouse rather than polling the Analytics API.

Analytics

On this page