Engagement analytics

A loyalty program is only worth running if you can prove it changes behavior. This page covers the metrics that tell you whether VINR Engagement is healthy — enrollment, active members, points liability, redemption rate, and incremental revenue — and how to pull them via the dashboard, the API, and exports.

Key metricsAskCopy

Five numbers describe almost every program. Read them together: a metric in isolation usually misleads.

import { Vinr } from '@vinr/sdk';
const vinr = new Vinr({ secretKey: process.env.VINR_SECRET_KEY });

// Snapshot the headline metrics for a program over the last 30 days.
const report = await vinr.loyalty.analytics.summary({
  program: 'prog_default',
  period: { gte: '2026-05-01', lt: '2026-05-31' },
});

console.log(report.enrollment);        // 412 new members
console.log(report.activeMembers);     // 3187
console.log(report.pointsLiability);   // 1_284_500 minor units (EUR 12,845.00)
console.log(report.redemptionRate);    // 0.38

Liability & breakageAskCopy

Every point you award is a promise to honor it later. Liability is the EUR value of all outstanding points; breakage is the share you expect never to be redeemed because points expire or members go dormant. Breakage reduces the real cost of the program, but over-relying on it is a finance and, in some regions, a compliance risk.

const liability = await vinr.loyalty.analytics.liability({
  program: 'prog_default',
  asOf: '2026-05-30',
});

console.log(liability.outstandingPoints);   // 2_569_000 points
console.log(liability.value);                // 1_284_500 minor units
console.log(liability.expiringNext30Days);   // 95_000 points
console.log(liability.breakageRateTrailing); // 0.21  (21% historically expired)

Redemption & engagement ratesAskCopy

Redemption rate is the single best signal that rewards are desirable. Too low (under ~15%) and members do not see value; too high with rising liability can mean your earn rate is too generous.

• Redemption rate — points redeemed divided by points earned over a trailing 90 days.
• Earn participation — share of paying customers who earned at least once.
• Redeem participation — share of members who redeemed at least once.
• Time-to-first-redemption — median days from enrollment to first redemption.

A healthy program shows redeem participation climbing as members cross their first reward threshold. If time-to-first-redemption is long, your lowest reward tier is probably priced too high — see Rewards catalog.

Cohort & tier analysisAskCopy

Averages hide the story. Group members by enrollment month (cohort) or by tier to see where value concentrates and where members stall.

// Compare spend and retention across tiers.
const byTier = await vinr.loyalty.analytics.breakdown({
  program: 'prog_default',
  dimension: 'tier',
  metrics: ['activeMembers', 'avgSpend', 'redemptionRate'],
  period: { gte: '2026-03-01', lt: '2026-06-01' },
});

for (const row of byTier.rows) {
  console.log(row.tier, row.avgSpend, row.redemptionRate);
  // "silver" 4200 0.31 / "gold" 9800 0.52 ...
}

The two cuts answer different questions:

A common finding: the top tier drives most incremental revenue but contains few members, so the highest-leverage move is helping mid-tier members climb, not over-rewarding the top.

ExportsAskCopy

For finance reconciliation, BI tools, or ad-hoc analysis, export the underlying points_transaction ledger rather than working from rolled-up metrics. Exports run asynchronously and emit an event when ready.

curl -X POST https://api.vinr.com/v1/loyalty/analytics/exports \
  -H "X-Api-Key: $VINR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "program": "prog_default",
    "type": "points_transactions",
    "period": { "gte": "2026-05-01", "lt": "2026-06-01" },
    "format": "csv"
  }'

Listen for the completion event and download the file:

vinr.webhooks.on('loyalty.export.ready', (event) => {
  console.log(event.data.downloadUrl); // signed URL, expires in 24h
});

Next stepsAskCopy