---
title: "Get Loyalty metrics"
method: GET
path: "/v1/admin/metrics/loyalty"
tags: ["Metrics"]
---

# Get Loyalty metrics

`GET /v1/admin/metrics/loyalty`

## Request

- Base URL: `https://api.prod.keyban.io`
- URL: `https://api.prod.keyban.io/v1/admin/metrics/loyalty`
- Auth: `X-Api-Key` (a scheme the document does not define)

Retrieve loyalty program metrics including points in circulation, active accounts, visits, tier distribution, and digital wallet pass installation (Google and Apple). Platform admins see all organizations; organization members see only their organization.

## Query parameters

- `startDate` string, date
- `endDate` string, date
- `applicationId` string, uuid

## Response `200`

Loyalty metrics retrieved successfully

- LoyaltyMetricsByOrgDto[]
  - `organizationId` string, uuid, required: Organization UUID
  - `organizationName` string, required: Organization display name
  - `applications` object[], required: Metrics for each loyalty-enabled application in the organization
    - `applicationId` string, uuid, required: Application UUID
    - `applicationName` string, required: Application display name
    - `metrics` object, required: Loyalty metrics for this application
      - `pointsInCirculation` string, required: Total loyalty points minted during the period (sum of mint transactions from the blockchain indexer). Returned as a BigInt string for JSON compatibility.
      - `pointsBurned` string, required: Total loyalty points burned/redeemed during the period (sum of burn transactions from the blockchain indexer). Returned as a BigInt string for JSON compatibility.
      - `netCirculation` string, required: Net points change during the period, computed as (pointsInCirculation - pointsBurned). A positive value means more points were minted than burned in the selected date range. This is a period delta, not a historical total supply. Returned as a BigInt string for JSON compatibility.
      - `activeAccounts` integer, required: Number of customer accounts with point balance > 0 and activity during the period
      - `totalVisits` integer, required: Total number of customer visits tracked in the date range
      - `tierDistribution` object[], required: Distribution of customers across loyalty tiers (Bronze, Silver, Gold, etc.)
        - `tierName` string, required: Display name of the reward tier
        - `requiredVisits` integer, required: Number of visits required to achieve this tier
        - `accountCount` integer, required: Number of customer accounts at this tier level
      - `walletInstallation` object: Digital wallet pass installation metrics (Google and Apple Wallet). Optional so that a newly deployed frontend can still parse responses from a backend rolling out this field; will become required once the backend is fully deployed.
        - `googleInstalled` integer, required: Number of customer accounts with Google Wallet pass installed (tracked by first click on "Add to Google Wallet" button)
        - `googlePercentage` number, required: Percentage of total accounts with Google Wallet installed (0-100, or 0 if total accounts = 0)
        - `appleInstalled` integer, required: Number of customer accounts with Apple Wallet pass installed (tracked by active device registrations)
        - `applePercentage` number, required: Percentage of total accounts with Apple Wallet installed (0-100, or 0 if total accounts = 0)
        - `combinedInstalled` integer, required: Number of distinct customer accounts with at least one wallet pass (Google OR Apple). Accounts with both passes are counted once.
        - `combinedPercentage` number, required: Percentage of total accounts with at least one wallet pass (0-100, or 0 if total accounts = 0)
        - `totalAccounts` integer, required: Total accounts in the application (the account table has no soft-delete, so every row is counted). Denominator for every percentage above.

## Other responses

- `401`: Unauthorized
- `403`: Metrics access denied

---

[API](https://skmtc.dev/keyban/apis/keyban-rest-apis.md) · [All operations](https://skmtc.dev/keyban/apis/keyban-rest-apis/llms.txt) · [OpenAPI document](https://skmtc.dev/keyban/apis/keyban-rest-apis/revisions/0bb79a1da961?raw)