Loyalty & Rewards

Overview

The Loyalty API lets you create points-based programs that reward customers for every purchase. Define how many points each dollar earns, set up tiers with escalating benefits, and curate a rewards catalog that customers can redeem against their balance.

Points are earned automatically when an order is completed. You can also award points manually for birthdays, referrals, or any custom event. The system tracks lifetime points, current balance, tier status, and full transaction history per customer.

Create a Program

Define a loyalty program with a name, earning rate, and optional tiers. Tiers unlock as customers accumulate lifetime points, granting multipliers and perks.

const whale = new WhaleClient({ apiKey: 'wk_live_...' })

// Create a loyalty program with tiers
const program = await whale.loyalty.create({
  name: 'VIP Rewards',
  points_per_dollar: 10,
  tiers: [
    { name: 'Bronze', min_points: 0, multiplier: 1.0 },
    { name: 'Silver', min_points: 5000, multiplier: 1.5 },
    { name: 'Gold', min_points: 15000, multiplier: 2.0 },
    { name: 'Platinum', min_points: 50000, multiplier: 3.0 }
  ]
})

// Response
{
  "id": "loy_550e8400-e29b-41d4-a716-446655440000",
  "name": "VIP Rewards",
  "points_per_dollar": 10,
  "tiers": [
    { "name": "Bronze", "min_points": 0, "multiplier": 1.0 },
    { "name": "Silver", "min_points": 5000, "multiplier": 1.5 },
    { "name": "Gold", "min_points": 15000, "multiplier": 2.0 },
    { "name": "Platinum", "min_points": 50000, "multiplier": 3.0 }
  ],
  "is_active": true,
  "created_at": "2026-03-10T12:00:00.000Z"
}

// Update the earning rate
await whale.loyalty.update('loy_550e8400...', {
  points_per_dollar: 15
})

Earn Points

Points are earned automatically when an order is completed — the system calculates the award based on the order total and the customer's tier multiplier. You can also award points manually for any reason.

const whale = new WhaleClient({ apiKey: 'wk_live_...' })

// Automatic: points are awarded when order status → completed
// A $50 order for a Gold member (2x multiplier, 10 pts/$):
// 50 × 10 × 2.0 = 1,000 points earned automatically

// Manual: award bonus points
const earning = await whale.loyalty.earn('cust_abc123', {
  points: 500,
  reason: 'Birthday bonus'
})

// Response
{
  "id": "txn_770e8400-e29b-41d4-a716-446655440000",
  "customer_id": "cust_abc123",
  "type": "earn",
  "points": 500,
  "reason": "Birthday bonus",
  "balance_after": 3500,
  "created_at": "2026-03-10T12:00:00.000Z"
}

// Bulk award for a promotion
const customers = ['cust_abc123', 'cust_def456', 'cust_ghi789']

for (const id of customers) {
  await whale.loyalty.earn(id, {
    points: 200,
    reason: 'Spring promotion'
  })
}

Redeem Rewards

Browse the rewards catalog to see what's available, then redeem a reward for a customer. The system verifies the customer has enough points and deducts the cost from their balance.

const whale = new WhaleClient({ apiKey: 'wk_live_...' })

// List available rewards
const rewards = await whale.loyalty.rewards.list()

// Response
{
  "data": [
    { "id": "rwd_001", "name": "10% Off Next Order", "points_cost": 1000, "type": "discount" },
    { "id": "rwd_002", "name": "Free Shipping", "points_cost": 500, "type": "shipping" },
    { "id": "rwd_003", "name": "$25 Store Credit", "points_cost": 2500, "type": "credit" },
    { "id": "rwd_004", "name": "Exclusive Early Access", "points_cost": 5000, "type": "perk" }
  ],
  "total": 4
}

// Redeem a reward
const redemption = await whale.loyalty.redeem('cust_abc123', 'rwd_002')

// Response
{
  "id": "txn_880e8400-e29b-41d4-a716-446655440000",
  "customer_id": "cust_abc123",
  "type": "redeem",
  "points": -500,
  "reward": { "id": "rwd_002", "name": "Free Shipping" },
  "balance_after": 3000,
  "created_at": "2026-03-10T12:00:00.000Z"
}

Customer Loyalty Status

Retrieve a customer's full loyalty profile including their current points balance, tier, lifetime points earned, and recent transactions.

const whale = new WhaleClient({ apiKey: 'wk_live_...' })

// Get a customer's loyalty status
const status = await whale.loyalty.get('cust_abc123')

// Response
{
  "customer_id": "cust_abc123",
  "points_balance": 3000,
  "lifetime_points": 12500,
  "tier": {
    "name": "Silver",
    "multiplier": 1.5,
    "next_tier": { "name": "Gold", "points_needed": 2500 }
  },
  "transactions": [
    { "id": "txn_880e...", "type": "redeem", "points": -500, "reason": "Free Shipping", "created_at": "2026-03-10T12:00:00.000Z" },
    { "id": "txn_770e...", "type": "earn", "points": 500, "reason": "Birthday bonus", "created_at": "2026-03-10T11:00:00.000Z" },
    { "id": "txn_660e...", "type": "earn", "points": 1000, "reason": "Order #1042", "created_at": "2026-03-09T15:30:00.000Z" }
  ],
  "member_since": "2025-11-15T08:00:00.000Z"
}

Anomaly Detection

The system automatically monitors earning patterns and flags suspicious activity — such as unusually high point awards, rapid-fire earning from the same customer, or earning patterns that deviate significantly from historical norms. Flagged anomalies can be reviewed and resolved from the API or the dashboard.

const whale = new WhaleClient({ apiKey: 'wk_live_...' })

// List flagged anomalies
const anomalies = await whale.loyalty.anomalies.list()

// Response
{
  "data": [
    {
      "id": "anom_001",
      "customer_id": "cust_xyz789",
      "type": "rapid_earning",
      "description": "15 point transactions in 2 minutes",
      "points_involved": 7500,
      "status": "pending_review",
      "flagged_at": "2026-03-10T14:22:00.000Z"
    },
    {
      "id": "anom_002",
      "customer_id": "cust_def456",
      "type": "unusual_amount",
      "description": "Single earning of 50,000 points (10x normal)",
      "points_involved": 50000,
      "status": "pending_review",
      "flagged_at": "2026-03-10T13:15:00.000Z"
    }
  ],
  "total": 2
}

API Reference