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 loyalpro.points.award({
customer_id: "cus_abc123",
points: 100,
reason: "Purchase",
metadata: {
order_id: "order_12345",
amount: 10000 // ₦10,000
}
});
// Award bonus points
await loyalpro.points.award({
customer_id: "cus_abc123",
points: 50,
reason: "Birthday Bonus",
type: "bonus"
});
// Award points with expiration
await loyalpro.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 loyalpro.customers.retrieve("cus_abc123");
console.log(customer.points_balance); // 500
// Redeem points for a reward
const redemption = await loyalpro.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 loyalpro.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}`);
});