Loyalty Program Example

This example enrolls a client, issues a pass, awards points, and reads the wallet ledger.

import { WalletHero } from "@wallethero/sdk";

const walletHero = new WalletHero({
  apiToken: process.env.WALLETHERO_API_TOKEN!,
});

const workspaceId = "workspace-uuid";
const projectId = "project-uuid";
const templateId = "template-uuid";

const { data: customer } = await walletHero.clients.create(workspaceId, {
  workspace_id: workspaceId,
  first_name: "Jane",
  last_name: "Customer",
  email: "[email protected]",
  loyalty_program_enabled: true,
  marketing_consent: true,
  marketing_consent_text: "I agree to receive loyalty updates.",
  custom_fields: { preferred_store: "Downtown" },
});

const { data: pass } = await walletHero.passes.create({
  workspace_id: workspaceId,
  project_id: projectId,
  pass_template_id: templateId,
  client_id: customer.id,
});

await walletHero.loyalty.earnPoints(workspaceId, {
  client_id: customer.id,
  wallet_type_code: "points",
  amount: 100,
  description: "Welcome bonus",
  external_id: "welcome-bonus:[email protected]",
});

const { data: balances } = await walletHero.loyalty.getClientWallets(
  workspaceId,
  customer.id,
);

const ledger = await walletHero.loyalty.getClientLedger(
  workspaceId,
  customer.id,
  { limit: 25 },
);

console.log(pass.apple_pass_url, balances, ledger.data);

Record a purchase

Use TransactionsService for normalized commerce records. Transaction ingestion is the path that drives transaction-side loyalty and automation behavior.

const { data: transaction } = await walletHero.transactions.create({
  workspace_id: workspaceId,
  client_id: customer.id,
  pass_id: pass.id,
  amount: 49.9,
  currency: "PLN",
  external_id: "receipt-1842",
  source: "pos",
  location: "Downtown",
  transaction_timestamp: new Date().toISOString(),
});

Multiple wallet types

const { data: bonusWallet } = await walletHero.loyalty.createWalletType(
  workspaceId,
  {
    workspace_id: workspaceId,
    code: "bonus",
    name: "Bonus points",
    unit_singular_name: "point",
    unit_plural_name: "points",
  },
);

await walletHero.loyalty.earnPoints(workspaceId, {
  client_id: customer.id,
  wallet_type_code: bonusWallet.code,
  amount: 25,
  description: "Seasonal bonus",
});

In templates, ${wallet.points} reads the default wallet and ${wallet:bonus.points} reads the wallet whose code is bonus.

Tiers and rewards

The authenticated client also exposes tiers, rewards, referrals, and automations. See the Loyalty API, Tiers API, and Rewards API for the domain rules behind those SDK methods.