Official Node.js SDK for the Livepasses API - generate, manage, and redeem Apple Wallet and Google Wallet passes.
npm install livepassesRequires Node.js 18+ (uses native fetch). Zero runtime dependencies.
import { Livepasses } from 'livepasses';
const client = new Livepasses('lp_api_key_...');
const result = await client.passes.generate({
templateId: 'your-template-id',
passes: [{
customer: { firstName: 'Jane', lastName: 'Doe', email: 'jane@example.com' },
businessData: { sectionInfo: 'A', rowInfo: '12', seatNumber: '5' },
}],
});
console.log(result.passes[0].platforms.apple.addToWalletUrl);Pass your API key when creating the client. Get your key at dashboard.livepasses.com/api-keys.
const client = new Livepasses('lp_api_key_...', {
baseUrl: 'https://api.livepasses.com', // default
timeout: 30000, // 30s default
maxRetries: 3, // default
});const result = await client.passes.generate({
templateId: 'template-id',
businessContext: {
event: {
eventName: 'Summer Concert 2026',
eventDate: '2026-07-15T18:00:00Z',
},
},
passes: [{
customer: { firstName: 'Jane', lastName: 'Doe', email: 'jane@example.com' },
businessData: {
sectionInfo: 'VIP', rowInfo: 'A', seatNumber: '12',
ticketType: 'VIP', price: 150, currency: 'USD',
},
}],
options: { deliveryMethod: 'email' },
});For multiple recipients, generateAndWait automatically polls until the batch completes:
const result = await client.passes.generateAndWait(
{
templateId: 'template-id',
passes: recipients.map(r => ({
customer: r,
businessData: { ticketType: 'General' },
})),
},
{
pollInterval: 2000, // 2s between polls (default)
onProgress: (status) => {
console.log(`${status.progressPercentage}% complete`);
},
},
);If you need more control over polling, use generate + getBatchStatus:
const initial = await client.passes.generate({
templateId: 'template-id',
passes: recipients.map(r => ({
customer: r,
businessData: { ticketType: 'General' },
})),
});
if (initial.batchOperation) {
let status = await client.passes.getBatchStatus(initial.batchOperation.batchId);
while (!status.isCompleted) {
await new Promise(r => setTimeout(r, 2000));
status = await client.passes.getBatchStatus(initial.batchOperation.batchId);
console.log(`Progress: ${status.progressPercentage}%`);
}
console.log(`Completed: ${status.statistics.successful} successful, ${status.statistics.failed} failed`);
}const pass = await client.passes.lookup({ passId: 'pass-id' });
// or by pass number
const pass = await client.passes.lookup({ passNumber: 'LP-001' });const validation = await client.passes.validate('pass-id');
if (validation.canBeRedeemed) {
// proceed with redemption
}// Generic redemption
const result = await client.passes.redeem('pass-id');
// Event check-in
const result = await client.passes.checkIn('pass-id', {
location: { name: 'Gate 1', latitude: 40.71, longitude: -74.00 },
});
// Coupon redemption
const result = await client.passes.redeemCoupon('pass-id');Update business data or context on an existing pass:
await client.passes.update('pass-id', {
businessData: { currentPoints: 750, memberTier: 'Platinum' },
businessContext: {
loyalty: { programUpdate: 'Congratulations on reaching Platinum!' },
},
});Update multiple passes at once:
await client.passes.bulkUpdate({
passIds: ['pass-1', 'pass-2', 'pass-3'],
businessData: { memberTier: 'Gold' },
businessContext: {
loyalty: { seasonalMessage: 'Happy holidays from our team!' },
},
});await client.passes.generate({
templateId: 'event-template-id',
businessContext: { event: { eventName: 'Concert', eventDate: '2026-07-15T18:00:00Z' } },
passes: [{
customer: { firstName: 'Jane', lastName: 'Doe' },
businessData: { sectionInfo: 'A', rowInfo: '1', seatNumber: '5', gateInfo: 'North' },
}],
});await client.passes.generate({
templateId: 'loyalty-template-id',
passes: [{
customer: { firstName: 'Jane', lastName: 'Doe', email: 'jane@example.com' },
businessData: { membershipNumber: 'MEM-001', currentPoints: 500, memberTier: 'Gold' },
}],
});
// Earn points
await client.passes.loyaltyTransact('pass-id', {
transactionType: 'earn',
points: 100,
description: 'Purchase reward',
});
// Spend points
await client.passes.loyaltyTransact('pass-id', {
transactionType: 'spend',
points: 50,
description: 'Reward redemption',
});await client.passes.generate({
templateId: 'coupon-template-id',
businessContext: { coupon: { campaignName: 'Summer Sale', specialMessage: '20% off!' } },
passes: [{
customer: { firstName: 'Jane', lastName: 'Doe' },
businessData: { promoCode: 'SUMMER20', maxUsageCount: 1 },
}],
});// List templates
const templates = await client.templates.list({ status: 'Active' });
// Get template details
const template = await client.templates.get('template-id');const template = await client.templates.create({
name: 'VIP Event Pass',
description: 'Premium event ticket template',
businessFeatures: {
passType: 'event',
hasSeating: true,
supportedPlatforms: ['apple', 'google'],
},
});const updated = await client.templates.update('template-id', {
name: 'VIP Event Pass v2',
description: 'Updated premium event ticket template',
});await client.templates.activate('template-id');
await client.templates.deactivate('template-id');// Register a webhook
const webhook = await client.webhooks.create({
url: 'https://your-app.com/webhooks/livepasses',
events: ['pass.generated', 'pass.redeemed', 'batch.completed'],
});
console.log(webhook.secret); // use this to verify webhook signatures
// List webhooks
const webhooks = await client.webhooks.list();
// Remove a webhook
await client.webhooks.delete('webhook-id');All errors are typed for precise catch handling:
import {
Livepasses,
LivepassesError,
AuthenticationError,
ValidationError,
ForbiddenError,
NotFoundError,
RateLimitError,
QuotaExceededError,
BusinessRuleError,
ApiErrorCodes,
} from 'livepasses';
try {
await client.passes.generate({ ... });
} catch (err) {
if (err instanceof AuthenticationError) {
console.error('Invalid API key');
} else if (err instanceof ValidationError) {
console.error('Invalid input:', err.message, err.details);
} else if (err instanceof ForbiddenError) {
console.error('Insufficient permissions for this operation');
} else if (err instanceof RateLimitError) {
console.error(`Rate limited. Retry after ${err.retryAfter}s`);
} else if (err instanceof QuotaExceededError) {
console.error('Monthly pass quota exceeded — upgrade your plan');
} else if (err instanceof NotFoundError) {
console.error('Template or pass not found');
} else if (err instanceof BusinessRuleError) {
console.error('Business rule:', err.message);
} else if (err instanceof LivepassesError) {
// Catch-all for any other API error
console.error(`API error [${err.code}]: ${err.message} (HTTP ${err.status})`);
}
}Use the ApiErrorCodes constant for programmatic error code comparisons:
import { LivepassesError, ApiErrorCodes } from 'livepasses';
try {
await client.passes.redeem('pass-id');
} catch (err) {
if (err instanceof LivepassesError) {
switch (err.code) {
case ApiErrorCodes.PASS_ALREADY_USED:
console.error('This pass has already been redeemed');
break;
case ApiErrorCodes.PASS_EXPIRED:
console.error('This pass has expired');
break;
case ApiErrorCodes.TEMPLATE_INACTIVE:
console.error('The template for this pass is inactive');
break;
default:
console.error(`Unhandled error: ${err.code}`);
}
}
}| Error Class | HTTP Status | When |
|---|---|---|
AuthenticationError |
401 | Invalid, expired, or revoked API key |
ValidationError |
400 | Request validation failed |
ForbiddenError |
403 | Insufficient permissions |
NotFoundError |
404 | Resource not found |
RateLimitError |
429 | Rate limit exceeded |
QuotaExceededError |
403 | API quota or subscription limit exceeded |
BusinessRuleError |
422 | Business rule violation (pass expired, already used, etc.) |
const page1 = await client.passes.list({ page: 1, pageSize: 50 });
console.log(`Page 1 of ${page1.pagination.totalPages} (${page1.pagination.totalItems} total)`);
// Get next page
if (page1.pagination.currentPage < page1.pagination.totalPages) {
const page2 = await client.passes.list({ page: 2, pageSize: 50 });
}for await (const pass of client.passes.listAutoPaginate({ templateId: 'tpl-id' })) {
console.log(pass.id);
}| Option | Default | Description |
|---|---|---|
baseUrl |
https://api.livepasses.com |
API base URL |
timeout |
30000 |
Request timeout in ms |
maxRetries |
3 |
Max retries for failed requests (429, 5xx) |
The SDK automatically retries on:
- 429 Too Many Requests — honors
Retry-Afterheader - 5xx Server Errors — exponential backoff with jitter
The SDK is written in TypeScript and ships with full type declarations. All request params and response types are exported:
import type { GeneratePassesParams, PassGenerationResult, BatchStatusResult } from 'livepasses';See the examples/ directory for runnable scripts:
- generate-passes.ts — End-to-end pass generation, lookup, validation, and check-in
- loyalty-workflow.ts — Loyalty card lifecycle: generate, earn points, spend points, update tier
- coupon-workflow.ts — Coupon pass generation and redemption
- template-management.ts — CRUD operations on pass templates
- webhook-setup.ts — Register, list, and manage webhooks
Run any example with:
export LIVEPASSES_API_KEY="your-api-key"
npx tsx examples/generate-passes.tsMIT