Tiers

Tiers (membership levels) recognize your most engaged members with exclusive benefits, higher point multipliers, and tier-locked rewards. Tiers are calculated automatically from total points earned, or can be assigned manually.

List Tiers

Fetch all tiers configured for your program.

GET /api/v1/tiers

SDK

const tiers = await useLoyalty.tiers.list();

Response

[
  {
    "id": "tier_bronze",
    "name": "Bronze",
    "level": 1,
    "minPoints": 0,
    "maxPoints": 999,
    "color": "#CD7F32",
    "benefits": {
      "pointsMultiplier": 1.0,
      "exclusiveRewards": false
    }
  },
  {
    "id": "tier_silver",
    "name": "Silver",
    "level": 2,
    "minPoints": 1000,
    "maxPoints": 4999,
    "color": "#C0C0C0",
    "benefits": {
      "pointsMultiplier": 1.25,
      "exclusiveRewards": true
    }
  },
  {
    "id": "tier_gold",
    "name": "Gold",
    "level": 3,
    "minPoints": 5000,
    "maxPoints": null,
    "color": "#FFD700",
    "benefits": {
      "pointsMultiplier": 1.5,
      "exclusiveRewards": true,
      "prioritySupport": true
    }
  }
]

Get Tier

Fetch a single tier by ID.

GET /api/v1/tiers/:tierId

SDK

const tier = await useLoyalty.tiers.get('tier_gold');

Get Member's Current Tier

Retrieve the tier a member currently holds.

GET /api/v1/members/:externalId/tier

SDK

const tier = await useLoyalty.tiers.getMemberTier('user_123');
// null if member hasn't reached any tier threshold yet

Response

{
  "id": "tier_silver",
  "name": "Silver",
  "level": 2,
  "minPoints": 1000,
  "maxPoints": 4999,
  "color": "#C0C0C0",
  "benefits": {
    "pointsMultiplier": 1.25
  }
}

Assign Tier Manually

Override the auto-calculated tier for a member. Useful for VIP onboarding or promotions.

POST /api/v1/members/:externalId/tier

Request Body

{
  "tierId": "tier_gold"
}

SDK

const result = await useLoyalty.tiers.assign('user_123', 'tier_gold');

Response

{
  "memberId": "clx123abc",
  "previousTier": {
    "id": "tier_silver",
    "name": "Silver",
    "level": 2
  },
  "newTier": {
    "id": "tier_gold",
    "name": "Gold",
    "level": 3
  },
  "automatic": false
}

Recalculate Tier

Remove any manual override and recalculate the tier from the member's current total points earned.

POST /api/v1/members/:externalId/tier/recalculate

SDK

const result = await useLoyalty.tiers.recalculate('user_123');
// result.automatic === true

Code Examples

Show Tier Progress in UI

async function getTierProgress(userId: string) {
  const [tiers, member] = await Promise.all([
    useLoyalty.tiers.list(),
    useLoyalty.members.get(userId),
  ]);

  const currentTier = member.tier;
  const sortedTiers = tiers.sort((a, b) => a.level - b.level);
  const nextTier = sortedTiers.find(
    t => t.level > (currentTier?.level ?? 0)
  );

  return {
    currentTier,
    nextTier,
    pointsToNextTier: nextTier
      ? Math.max(0, nextTier.minPoints - member.totalPointsEarned)
      : 0,
    progressPercent: nextTier
      ? Math.min(100, (member.totalPointsEarned / nextTier.minPoints) * 100)
      : 100,
  };
}

Tier-Gated Content

async function canAccessVipContent(userId: string): Promise<boolean> {
  const tier = await useLoyalty.tiers.getMemberTier(userId);
  return tier !== null && tier.level >= 3; // Gold or above
}

Listen for Tier Changes in Event Results

When tracking events, the result tells you if the event caused a tier upgrade:

const result = await useLoyalty.events.track('user_123', {
  event: 'purchase_completed',
  properties: { amount: 200 },
});

if (result.tierChanged) {
  console.log(`Member upgraded to: ${result.newTier}`);
  // Notify the user!
}

Auto-Calculation vs Manual Assignment

Scenario	Recommended approach
Standard progression by points	Auto (default) — no action needed
VIP onboarding (skip tiers)	`tiers.assign()` then `tiers.recalculate()` when points catch up
Tier demotion after inactivity	`tiers.assign()` with lower tier
Tier matched to external subscription	`tiers.assign()` on subscription change event

Tiers

On this page