WalletHero SDK

The official TypeScript SDK provides typed access to WalletHero's authenticated management API and its public enrollment and loyalty surfaces.

Raw HTTP API

For another language or direct HTTP integration, use the API Reference.

Installation

npm install @wallethero/sdk

Node.js 18 or newer is required. The package includes CommonJS, ES module, and TypeScript declaration builds.

Authenticated client

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

const client = new WalletHero({
  apiToken: process.env.WALLETHERO_API_TOKEN!,
  // apiUrl: "https://api.wallethero.app",
  // timeout: 30_000,
});

const connected = await client.ping();
const { data: user } = await client.me();

console.log(connected, user.email);

apiUrl defaults to https://api.wallethero.app. Call client.setToken(token) when a refreshed token must be applied to an existing client.

Response envelopes

Entity methods generally return { data: T }. List methods generally return { data: T[], meta? }.

const { data: templates, meta } =
  await client.passTemplates.getByWorkspace("workspace-uuid");

const { data: template } =
  await client.passTemplates.get(templates[0].id);

Some analytics, public-client, and convenience methods intentionally return their result directly. TypeScript exposes the exact return type for every method.

Workspace scoping

Workspace-owned resources must be scoped to a workspace. Prefer methods with an explicit workspaceId argument:

const workspaceId = "workspace-uuid";

const { data: projects } = await client.projects.getByWorkspace(workspaceId);
const { data: templates } = await client.passTemplates.getByWorkspace(workspaceId);
const customers = await client.clients.list(workspaceId, { limit: 50 });

When a legacy list(options) method is the appropriate API, pass filter.workspace_id._eq. Unscoped cross-workspace listing is rejected for tenant-owned resources.

Service catalog

Client property	Capabilities
automations	Automation rules, execution history, and metadata
campaigns	Lifecycle, audience, actions, errors, and statistics
clients	Identity, consent, custom fields, events, and passes
distributions	Hosted distributions, publishing, duplication, and token rotation
events	Create, batch, query, delete, and aggregate events
files	Upload, read, list, update, and delete files
imageSource	Preview and refresh remote template images
integrations	Provider configs, tests, health, webhooks, and import jobs
loyalty	Config, wallet types, balances, points, transfers, and ledger
loyaltyPortalConfig	Public loyalty portal settings
mobileAppConfig	Mobile branding, fields, actions, and runtime config
mobileAppUsers	Pairing, sessions, linked users, status, and revocation
notifications	Notification history and delivery status
passes	Issue, update, refresh, notify, resend, and switch templates
passTemplates	Template lifecycle, images, and iOS deeplinks
projects	Project lifecycle, templates, passes, and statistics
qrCodes	Apple and Google pass links and QR codes
referrals	Program config, referrals, analytics, completion, and cancellation
reports	Dashboard and activity reports
rewards	Catalog, availability, redemption lifecycle, and analytics
segments	Filters, size, previews, clients, passes, and duplication
systemAdmin	System-administrator workspace operations
tiers	Tier sets, assignments, progress, and recalculation jobs
transactions	Ingestion, assignment, queries, and analytics
webhooks	Configs, secrets, deliveries, tests, and retries
workspaceSettings	Workspace settings
workspaces	Workspaces, members, feature flags, data models, and certificates

Standalone public clients

The public clients do not use an account API token and are not properties of WalletHero.

Embedded enrollment

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

const distribution = new PublicDistributionService({
  apiUrl: "https://api.wallethero.app",
  distributionToken: "wh_dist_...",
});

const config = await distribution.getConfig();
const enrollment = await distribution.enroll({
  email: "[email protected]",
  first_name: "Jane",
  marketing_consent: true,
});

The browser origin must appear in the distribution's allowed_origins. Treat the optional enrollment.client_token as short-lived and do not persist it server-side.

Public loyalty portal

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

const portal = new PublicLoyaltyService({
  apiUrl: "https://api.wallethero.app",
});

await portal.createSession("workspace-slug", "client-uuid");

const profile = await portal.getMe();
const balances = await portal.getBalance();
const rewards = await portal.listRewards();

createSession() stores the returned short-lived token in the service. An existing token may also be supplied to the constructor or installed with setToken().

Error handling

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

try {
  await client.passes.get("missing-pass-id");
} catch (error) {
  if (error instanceof WalletHeroError) {
    console.log(error.status, error.code, error.message, error.details);
  }
}

ping() returns false instead of throwing when its connection check fails.

Next steps

• Quickstart
• Types reference
• REST API reference