Tiers & status

Tiers grant escalating benefits as members qualify through spend or points. VINR tracks qualification, promotion, and demotion automatically, emitting events at every transition so your app and your member communications stay in sync.

How tiers fit a programAskCopy

A program holds an ordered list of tiers, each with a numeric rank (0 is the entry tier). A member always sits in exactly one tier. VINR continuously evaluates each member's qualifying value against tier thresholds and moves them up or down — you never write promotion logic yourself.

Defining tiersAskCopy

Define tiers on the program, lowest rank first. Each tier names a threshold expressed in the program's qualifying metric.

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

await vinr.loyalty.programs.update('prog_default', {
  tierConfig: {
    qualifyOn: 'spend',          // 'spend' | 'points' | 'custom'
    period: { type: 'rolling', months: 12 },
    tiers: [
      { name: 'Member', rank: 0, threshold: 0 },
      { name: 'Silver', rank: 1, threshold: 50000 },   // EUR 500 spend
      { name: 'Gold',   rank: 2, threshold: 150000 },  // EUR 1,500
      { name: 'Platinum', rank: 3, threshold: 500000 },// EUR 5,000
    ],
  },
});

Thresholds use the same minor-unit integers as everywhere else in VINR when qualifyOn is spend (50000 = EUR 500.00), or raw point counts when qualifyOn is points.

Qualification criteriaAskCopy

The qualifyOn setting decides what counts toward status:

For custom, advance a member's qualifying value yourself — for example, one credit per completed stay:

await vinr.loyalty.accounts.recordQualifyingActivity('loy_abc123', {
  amount: 1,                       // one qualifying unit
  reason: 'stay.completed',
  reference: 'pay_9f2a',
});

Promotion & demotionAskCopy

VINR re-evaluates a member whenever their qualifying value changes — after a payment.completed, a points award, or a recorded custom activity. Transitions are immediate and idempotent.

Subscribe to the transition event to trigger member communications or unlock app features:

const event = vinr.webhooks.verify(payload, signature); // x-vinr-signature

if (event.type === 'loyalty.tier.changed' && event.data.direction === 'up') {
  await sendCongratsEmail(event.data.account, event.data.toTier);
}

Tier benefitsAskCopy

Benefits are configuration, not code — VINR applies them automatically when a member acts. Common benefits:

• Earn multipliers — Gold earns 1.5x points per euro. Stacks with earning rules.
• Exclusive rewards — gate catalog items to a minimum rank so only Platinum can redeem them.
• Reduced redemption cost — discount the points price of rewards for higher tiers.

Read a member's current tier and active benefits at any time:

const member = await vinr.loyalty.accounts.retrieve('loy_abc123');
console.log(member.tier.name);            // "Gold"
console.log(member.tier.earnMultiplier);  // 1.5
console.log(member.qualifyingValue);      // 162000 (EUR 1,620 this period)

Tier periods & resetsAskCopy

The period controls how qualifying value accumulates and when it resets.

A reset re-baselines qualifying value to zero but never touches a member's redeemable points balance. To preview where members stand before a calendar reset, query qualification without waiting for the period to close:

const standings = await vinr.loyalty.accounts.list({
  program: 'prog_default',
  tier: 'Gold',
  atRisk: true,          // below threshold for next period
});

Next stepsAskCopy