Quickstart

Build your first mobile wallet pass in 5 minutes.

Prerequisites

• Node.js 18+
• A WalletHero account with an API token

Step 1: Install the SDK

npm install @wallethero/sdk

Step 2: Initialize the Client

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

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

// Verify connection
const connected = await client.ping();
if (!connected) {
  throw new Error('Failed to connect to WalletHero API');
}

Step 3: Create a Pass Template

// First, get your workspace and project IDs
const me = await client.me();
console.log('Logged in as:', me.email);

// Create a loyalty card template
const template = await client.passTemplates.create({
  name: 'Coffee Rewards Card',
  workspace_id: 'your-workspace-id',
  project_id: 'your-project-id',
  apple_pass_type_identifier: 'pass.com.yourcompany.loyalty',
  background_color: '#8B4513',
  label_color: '#FFFFFF',
  value_color: '#FFD700',
  logo_text: 'Coffee Co.',
  barcode_type: 'qr',
  barcode_id: 'id',
  top_field_label: 'POINTS',
  top_field_value: '{{points}}',
  front_fields: [
    { label: 'Member', value: '{{full_name}}' },
    { label: 'Tier', value: '{{tier}}' }
  ],
  back_fields: [
    { label: 'Terms', value: 'Earn 1 point per $1 spent.' }
  ]
});

console.log('Template created:', template.id);

Step 4: Issue a Pass

const pass = await client.passes.create({
  pass_template_id: template.id,
  project_id: 'your-project-id',
  workspace_id: 'your-workspace-id',
  full_name: 'Jane Customer',
  email: '[email protected]',
  custom_fields: {
    points: 0,
    tier: 'Bronze',
    member_since: new Date().toISOString().split('T')[0]
  }
});

console.log('Pass created:', pass.id);
console.log('Apple Wallet:', pass.apple_pass_url);
console.log('Google Wallet:', pass.google_pass_url);

Step 5: Update the Pass

// Add points and send notification
await client.passes.update(pass.id, {
  notification: 'You earned 50 points!',
  custom_fields: {
    points: 50,
    last_visit: new Date().toISOString()
  }
});

Step 6: Track Events

// Record a purchase
await client.events.recordPurchase(pass.id, {
  amount: 4.50,
  currency: 'USD',
  metadata: {
    items: ['Latte'],
    store: 'Downtown'
  }
});

// Record a check-in
await client.events.recordCheckIn(pass.id, {
  source: 'store-downtown'
});

Complete Example

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

async function main() {
  const client = new WalletHero({
    apiToken: process.env.WALLETHERO_API_TOKEN!
  });

  // Create a pass from existing template
  const pass = await client.passes.create({
    pass_template_id: 'your-template-id',
    project_id: 'your-project-id',
    workspace_id: 'your-workspace-id',
    full_name: 'Jane Customer',
    email: '[email protected]',
    custom_fields: {
      points: 100,
      tier: 'Silver'
    }
  });

  console.log('Pass URLs:');
  console.log('  Apple:', pass.apple_pass_url);
  console.log('  Google:', pass.google_pass_url);

  // Track a purchase
  await client.events.recordPurchase(pass.id, {
    amount: 25.00,
    currency: 'USD'
  });

  // Update points
  await client.passes.update(pass.id, {
    notification: 'Thanks for your purchase!',
    custom_fields: { points: 125 }
  });
}

main().catch(console.error);

Next Steps

• Pass Templates Service - Customize pass designs
• Segments - Target specific users
• Campaigns - Automate updates
• Events - Track user activity