TypeScript SDK

Installation

# npm
npm install @ploints/sdk

# pnpm
pnpm add @ploints/sdk

# yarn
yarn add @ploints/sdk

Create a Client

Import the SDK and initialize it with your API key. Never expose your key in client-side code.

import { PlointsClient } from "@ploints/sdk";

const ploints = new PlointsClient({
  apiKey: process.env.PLOINTS_API_KEY!,
});

Points

Award Points

const result = await ploints.points.award({
  customerEmail: "jane@example.com",
  amount: 100,
  description: "Purchase #1234",
});

console.log(result.data);
// { customerEmail: "jane@example.com", pointsAwarded: 100, newBalance: 350 }

Redeem Points

const result = await ploints.points.redeem({
  customerEmail: "jane@example.com",
  amount: 50,
  description: "Reward: Free Coffee",
});

console.log(result.data);
// { customerEmail: "jane@example.com", pointsRedeemed: 50, newBalance: 300 }

Get Balance

const result = await ploints.points.balance("jane@example.com");

console.log(result.data);
// { customerEmail: "jane@example.com", balance: 300, tier: "Gold" }

Customers

Create a Customer

const result = await ploints.customers.create({
  email: "jane@example.com",
  name: "Jane Doe",
  phone: "+1234567890", // optional
});

console.log(result.data);
// { id: "cust_abc123", email: "jane@example.com", name: "Jane Doe" }

List Customers

const result = await ploints.customers.list({ page: 1 });

console.log(result.data);
// { customers: [...], page: 1, totalPages: 5 }

Badges

Issue a Badge

const result = await ploints.badges.issue({
  customerEmail: "jane@example.com",
  badgeSlug: "first-purchase",
});

console.log(result.data);
// { badgeSlug: "first-purchase", issuedAt: "2025-06-15T10:30:00Z" }

Webhooks

Register a Webhook

const result = await ploints.webhooks.create({
  url: "https://yoursite.com/webhooks/ploints",
  events: ["points.earned", "customer.created"],
});

console.log(result.data);
// { id: "wh_abc123", url: "...", secret: "whsec_k8x2..." }

List Webhooks

const result = await ploints.webhooks.list();

console.log(result.data);
// [{ id: "wh_abc123", url: "...", events: [...] }]

Webhook Signature Verification

The SDK includes a helper to verify incoming webhook signatures using HMAC-SHA256:

import { verifyWebhookSignature } from "@ploints/sdk";

// In your webhook handler
const rawBody = await req.text();
const signature = req.headers.get("x-ploints-signature")!;

const isValid = verifyWebhookSignature({
  payload: rawBody,
  signature,
  secret: process.env.PLOINTS_WEBHOOK_SECRET!,
});

if (!isValid) {
  return new Response("Invalid signature", { status: 401 });
}

const event = JSON.parse(rawBody);
// Process event...

Error Handling

The SDK throws a PlointsError for non-2xx responses. Catch it to inspect the status code and error message:

import { PlointsClient, PlointsError } from "@ploints/sdk";

const ploints = new PlointsClient({ apiKey: process.env.PLOINTS_API_KEY! });

try {
  await ploints.points.redeem({
    customerEmail: "jane@example.com",
    amount: 99999,
  });
} catch (err) {
  if (err instanceof PlointsError) {
    console.error(err.status);  // 422
    console.error(err.message); // "Insufficient points"
  }
}

TypeScript Types

The SDK is fully typed. Import specific types if needed:

import type {
  AwardPointsRequest,
  AwardPointsResponse,
  RedeemPointsRequest,
  BalanceResponse,
  CreateCustomerRequest,
  WebhookEvent,
} from "@ploints/sdk";