Overview
Points are the currency of your loyalty program. This guide covers all the ways you can manage points for your customers - from awarding points on purchases to handling redemptions and adjustments.
Award Points
Redeem Points
Adjust Points
View History
Awarding Points
Award points to customers for purchases, referrals, or special events.
Award Points
// Award points for a purchase
const transaction = await loyalypro.points.award({
customer_id: "cus_abc123",
points: 100,
reason: "Purchase",
metadata: {
order_id: "order_12345",
amount: 10000 // ₦10,000
}
});
// Award bonus points
await loyalypro.points.award({
customer_id: "cus_abc123",
points: 50,
reason: "Birthday Bonus",
type: "bonus"
});
// Award points with expiration
await loyalypro.points.award({
customer_id: "cus_abc123",
points: 200,
reason: "Promotional Campaign",
expires_at: "2025-12-31T23:59:59Z"
});Redeeming Points
Process point redemptions when customers claim rewards.
Redeem Points
// Check customer balance first
const customer = await loyalypro.customers.retrieve("cus_abc123");
console.log(customer.points_balance); // 500
// Redeem points for a reward
const redemption = await loyalypro.points.redeem({
customer_id: "cus_abc123",
reward_id: "rwd_xyz789",
points: 200
});
// Generate redemption code for POS
console.log(redemption.code); // "REDEEM-ABC123"
console.log(redemption.discount_amount); // 1000 (₦1,000)Important
Always check the customer's balance before attempting a redemption to avoid "insufficient_balance" errors.
Viewing Points History
Track all points transactions for a customer.
Get Points History
// Get points transaction history
const history = await loyalypro.points.list({
customer_id: "cus_abc123",
limit: 20,
order: "desc"
});
// Each transaction includes:
// - id, type (earned/redeemed/expired/adjusted)
// - points, balance_after
// - reason, metadata
// - created_at
history.data.forEach(txn => {
console.log(`${txn.type}: ${txn.points} points - ${txn.reason}`);
});