Loyalty
Docs

Search...

⌘K

Settings

Complete reference for all Loyalty SDK configuration settings. These options control program behavior, API communication, and feature flags.

Client Options

The following options can be passed to the LoyaltyClient constructor:

typescript

import { LoyaltyClient } from "@loyalty/sdk";

const loyalty = new LoyaltyClient({
  // Required
  apiKey: string,
  apiSecret: string,
  programId: string,

  // Optional
  baseUrl: string,        // Default: "https://api.loyalty.dev"
  timeout: number,        // Default: 30000 (ms)
  retries: number,        // Default: 3
  debug: boolean,         // Default: false
  webhookSecret: string,  // For webhook verification
});

Program Settings

Program-level settings are defined in your loyalty.config.ts file and control the behavior of your loyalty program.

Point Settings

typescript

{
  points: {
    currency: "points",     // Display name for points
    precision: 0,           // Decimal places (0 = whole numbers)
    minAward: 1,            // Minimum points per transaction
    maxAward: 100000,       // Maximum points per transaction
    expiryDays: 365,        // Days until points expire (0 = never)
    expiryPolicy: "fifo",   // "fifo" | "lifo" | "none"
  }
}

Tier Settings

typescript

{
  tiers: {
    evaluationPeriod: "annual",  // "annual" | "monthly" | "rolling"
    downgradePolicy: "end_of_period", // "immediate" | "end_of_period"
    gracePeroid: 30,             // Days before downgrade
    qualifyingMetric: "earned",  // "earned" | "balance" | "spent"
  }
}

Evaluation period

The evaluation period determines how often tier status is reassessed. Annual evaluation resets at the start of each calendar year, while rolling evaluation uses a sliding window.

Webhook Configuration

Configure webhooks to receive real-time notifications about loyalty events:

typescript

{
  webhooks: {
    url: "https://your-app.com/api/loyalty/webhook",
    secret: process.env.LOYALTY_WEBHOOK_SECRET,
    events: [
      "points.awarded",
      "points.redeemed",
      "tier.upgraded",
      "tier.downgraded",
      "reward.redeemed",
    ],
    retryPolicy: {
      maxRetries: 5,
      backoffMultiplier: 2,
    },
  }
}

Feature Flags

Enable or disable specific features in your loyalty program:

typescript

{
  features: {
    referrals: true,
    bonusPoints: true,
    pointTransfers: false,
    socialSharing: true,
    gamification: false,
  }
}