Loyalty
Docs

Search...

⌘K

Loyalty Points

Learn how to implement a points system using the Loyalty SDK. This guide covers awarding points, checking balances, and handling point transactions.

Overview

Points are the core currency of your loyalty program. Members earn points through actions like purchases, referrals, and engagement, then redeem them for rewards.

Awarding Points

Use the awardPoints method to grant points to a member. The method accepts a member ID, the number of points, and an optional reason.

typescript

import loyalty from "@/lib/loyalty";

// Award points for a purchase
const transaction = await loyalty.points.award({
  memberId: "user_123",
  points: 500,
  reason: "Purchase order #4567",
  metadata: {
    orderId: "4567",
    amount: 49.99,
  },
});

console.log(transaction.id); // "txn_abc123"
console.log(transaction.balance); // Updated balance

Checking Balances

Retrieve a member's current point balance and transaction history:

typescript

// Get current balance
const balance = await loyalty.points.getBalance("user_123");
console.log(balance.available); // 1500
console.log(balance.pending);   // 200
console.log(balance.lifetime);  // 5000

// Get transaction history
const history = await loyalty.points.getHistory("user_123", {
  limit: 20,
  offset: 0,
});

Point Multipliers

Multipliers allow you to boost point earnings for specific actions, promotions, or tier levels. They stack with the member's tier multiplier.

typescript

// Award double points during a promotion
const transaction = await loyalty.points.award({
  memberId: "user_123",
  points: 500,
  multiplier: 2, // 500 * 2 = 1000 points awarded
  reason: "Double points weekend",
});

Multiplier stacking

When a multiplier is specified, it stacks with the member's tier multiplier. A Gold tier member (2x) with a 2x promotion multiplier will earn 4x points.

Implementation Steps

1

Set up the client

Initialize the Loyalty client with your API credentials as shown in the Installation guide.
2

Define earning rules

Configure when and how members earn points — purchases, sign-ups, referrals, or custom events.
3

Integrate point awards

Call the awardPoints method at the appropriate points in your application flow.
4

Display balances

Show members their current balance and transaction history in your UI.

Error Handling

Always wrap point operations in try/catch blocks to handle network errors and validation failures gracefully:

typescript

try {
  const transaction = await loyalty.points.award({
    memberId: "user_123",
    points: 500,
    reason: "Purchase",
  });
} catch (error) {
  if (error.code === "INSUFFICIENT_BALANCE") {
    // Handle insufficient balance
  } else if (error.code === "MEMBER_NOT_FOUND") {
    // Handle missing member
  } else {
    // Handle unexpected errors
    console.error("Points operation failed:", error);
  }
}