WalletHero SDK

The official TypeScript/JavaScript SDK for the WalletHero API. It provides typed clients for the authenticated management API, embedded distribution forms, and the public loyalty portal.

Installation

npm install @wallethero/sdk

Requirements:

• Node.js 18 or newer
• TypeScript 4 or newer when using TypeScript

The package ships CommonJS and ES module builds with bundled type declarations.

Authenticated client

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

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

const { data: user } = await walletHero.me();
const { data: workspaces } = await walletHero.workspaces.list();

console.log(user.email, workspaces.length);

apiUrl defaults to https://api.wallethero.app. Use setToken() to update an existing client's token without recreating its service instances.

Most entity methods return one of these envelopes:

interface ApiResponse<T> {
  data: T;
}

interface ApiListResponse<T> {
  data: T[];
  meta?: {
    total_count?: number;
    filter_count?: number;
  };
}

Create a client and pass

Identity and custom fields belong to the client. A pass references the client with client_id.

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]",
  marketing_consent: true,
  loyalty_program_enabled: true,
  custom_fields: { preferred_store: "Warsaw" },
});

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

console.log(pass.apple_pass_url, pass.google_pass_url);

For one-step enrollment, pass client_identity instead of client_id. The API creates or reuses a client in the workspace.

const { data: pass } = await walletHero.passes.create({
  workspace_id: workspaceId,
  project_id: projectId,
  pass_template_id: templateId,
  client_identity: {
    email: "[email protected]",
    first_name: "Alex",
    custom_fields: { member_number: "M-1042" },
  },
});

Workspace scoping

List and create operations for tenant-owned resources require a workspace ID. Prefer the explicit workspace methods:

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

Legacy list() methods that accept QueryOptions require filter.workspace_id._eq where the service cannot safely list across workspaces.

Services

| Property | Purpose | | --- | --- | | automations | Loyalty and lifecycle automation rules and executions | | campaigns | Campaign lifecycle, audiences, actions, and statistics | | clients | Customer identity, consent, custom fields, and client events | | distributions | Hosted distribution configuration and API-token rotation | | events | Event ingestion, queries, and aggregates | | files | File upload and management | | imageSource | Preview and refresh remote template images | | integrations | Provider configuration, health, webhooks, and import jobs | | loyalty | Loyalty configuration, wallets, points, and ledger entries | | loyaltyPortalConfig | Public loyalty portal configuration | | mobileAppConfig | Mobile app branding, fields, actions, and runtime config | | mobileAppUsers | Mobile app users, pairing, sessions, and status | | notifications | Notification history and delivery status | | passes | Pass lifecycle, bulk creation, template switching, and refresh | | passTemplates | Pass template lifecycle, images, and deeplinks | | projects | Workspace projects, templates, passes, and statistics | | qrCodes | Apple and Google pass URLs and QR codes | | referrals | Referral program configuration, records, and analytics | | reports | Workspace activity and dashboard reports | | rewards | Reward catalog, availability, and redemptions | | segments | Audience filters, previews, clients, and pass resolution | | systemAdmin | System-administrator workspace operations | | tiers | Tier sets, assignments, progress, and recalculation jobs | | transactions | Transaction ingestion, queries, and analytics | | webhooks | Webhook configuration, delivery history, and tests | | workspaceSettings | Workspace-level settings | | workspaces | Workspaces, members, data models, and certificates |

Embedded distribution client

PublicDistributionService is a standalone browser client for partner-hosted enrollment forms. It uses a distribution-scoped token, not an account API token.

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,
});

console.log(config.delivery_mode, enrollment.apple_pass_url);

Configure the embedding origin in the distribution's allowed_origins setting. Use the optional client_token returned by enroll() immediately for a loyalty-portal deep link; do not persist it server-side.

Public loyalty client

PublicLoyaltyService uses a short-lived client token and is separate from the account-authenticated client.

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();

console.log(profile, balances, rewards);

You can also construct the service with an existing token or call setToken() later. The service supports tier progress, redemptions, referrals, marketing consent, and verified account erasure.

Error handling

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

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

ping() is the exception: it returns false instead of throwing when the connection check fails.

Documentation

See the WalletHero SDK documentation and API reference.

License

MIT