AddToWallet

Easily create and manage Google Wallet and Apple Wallet passes with the official AddToWallet.co API client for Node.js and browsers.

• Homepage: AddToWallet.co
• Wallet pass builder:app.addtowallet.co
• API Docs: AddToWallet API Docs
• Live Demo: Wallet Pass Playground

Install

npm i addtowallet

Quick start (Node / server)

import { AddToWalletClient } from 'addtowallet';

const client = new AddToWalletClient({ apiKey: process.env.ADDTOWALLET_API_KEY! });

// Create a pass (example mirrors example_apps/wallet-pass-app/src/app/page.tsx)
const { cardId, passUrl } = await client.createPass({
  logoUrl: 'https://s3.amazonaws.com/i.addtowallet.co/assets/realestatelogo.png',
  cardTitle: 'Your Business Name',
  header: 'Amy Jane',
  textModulesData: [
    { id: 'r1start', header: 'Phone', body: '+1 8888888888' },
    { id: 'r1end', header: 'Email', body: '[email protected]' }
  ],
  linksModuleData: [
    { id: 'r1', description: 'Call Us', uri: 'tel:+1 8287489293' },
    { id: 'r2', description: 'Email Us', uri: 'mailto:[email protected]' },
    { id: 'r3', description: 'Visit our website', uri: 'https://app.addtowallet.co' },
    { id: 'r4', description: 'Visit our office', uri: 'geo:https://maps.google.com/?q=123+Main+Street,+Anytown,+CA' }
  ],
  barcodeType: 'QR_CODE',
  barcodeValue: '',
  barcodeAltText: '',
  hexBackgroundColor: '#141f31',
  appleFontColor: '#FFFFFF',
  heroImage: 'https://s3.amazonaws.com/i.addtowallet.co/assets/realestatehero.png'
});

console.log('Created pass:', cardId);
console.log('Shareable URL:', passUrl);

Core API (no UI)

import { AddToWalletClient } from 'addtowallet';

const client = new AddToWalletClient({ apiKey: process.env.ADDTOWALLET_API_KEY! });

// Create a pass (example mirrors example_apps/wallet-pass-app/src/app/page.tsx)
const { cardId, passUrl } = await client.createPass({
  logoUrl: 'https://s3.amazonaws.com/i.addtowallet.co/assets/realestatelogo.png',
  cardTitle: 'Your Business Name',
  header: 'Amy Jane',
  textModulesData: [
    { id: 'r1start', header: 'Phone', body: '+1 8888888888' },
    { id: 'r1end', header: 'Email', body: '[email protected]' }
  ],
  linksModuleData: [
    { id: 'r1', description: 'Call Us', uri: 'tel:+1 8287489293' },
    { id: 'r2', description: 'Email Us', uri: 'mailto:[email protected]' },
    { id: 'r3', description: 'Visit our website', uri: 'https://app.addtowallet.co' },
    { id: 'r4', description: 'Visit our office', uri: 'geo:https://maps.google.com/?q=123+Main+Street,+Anytown,+CA' }
  ],
  barcodeType: 'QR_CODE',
  barcodeValue: '',
  barcodeAltText: '',
  hexBackgroundColor: '#141f31',
  appleFontColor: '#FFFFFF',
  heroImage: 'https://s3.amazonaws.com/i.addtowallet.co/assets/realestatehero.png'
});
// Create a pass (example mirrors example_apps/wallet-pass-app/src/app/page.tsx)
const { cardId, passUrl } = await client.createPass({
  logoUrl: 'https://s3.amazonaws.com/i.addtowallet.co/assets/realestatelogo.png',
  cardTitle: 'Your Business Name',
  header: 'Amy Jane',
  textModulesData: [
    { id: 'r1start', header: 'Phone', body: '+1 8888888888' },
    { id: 'r1end', header: 'Email', body: '[email protected]' }
  ],
  linksModuleData: [
    { id: 'r1', description: 'Call Us', uri: 'tel:+1 8287489293' },
    { id: 'r2', description: 'Email Us', uri: 'mailto:[email protected]' },
    { id: 'r3', description: 'Visit our website', uri: 'https://app.addtowallet.co' },
    { id: 'r4', description: 'Visit our office', uri: 'geo:https://maps.google.com/?q=123+Main+Street,+Anytown,+CA' }
  ],
  barcodeType: 'QR_CODE',
  barcodeValue: '',
  barcodeAltText: '',
  hexBackgroundColor: '#141f31',
  appleFontColor: '#FFFFFF',
  heroImage: 'https://s3.amazonaws.com/i.addtowallet.co/assets/realestatehero.png'
});

// Update pass
await client.updatePass(cardId, {
  cardTitle: 'Updated Card Title',
  header: 'Updated Header',
  hexBackgroundColor: '#33FF57'
});

// Get credits
const { premiumCredits, freeCredits } = await client.getCredits();
console.log('Premium credits:', premiumCredits);
console.log('Free credits:', freeCredits);

// Get pass details
const pass = await client.getPass(cardId);
console.log('Pass title:', pass.cardTitle);


// Delete pass
const { msg } = await client.deletePass(cardId);
console.log('Pass deleted:', msg);

Secure frontend auth with short‑lived tokens

Never ship your AddToWallet secret in the browser. Instead, mint a short‑lived token on your server and use getAuthToken when constructing the client in browser code.

// Server route example: issue a short‑lived token your frontend can fetch
// Return JSON: { token: string }

Configuration

• baseUrl: defaults to https://app.addtowallet.co
• apiKey: server‑side secret key (do not use in browsers)
• getAuthToken: async function returning a short‑lived token for frontend use
• timeoutMs: optional request timeout

API Methods

• createPass(payload) → { msg: string, cardId: string, passUrl?: string }
• updatePass(cardId, payload) → { msg: string, updateStatus: UpdateStatus }
• deletePass(cardId) → { msg: string, deleteStatus: UpdateStatus }
• getCredits() → { premiumCredits: number, freeCredits: number }
• getPass(cardId) → PassDetails

Pass Data Structure

When creating or updating passes, use the following structure:

{
  cardTitle: 'My Loyalty Card',
  header: 'Welcome to Our Store',
  logoUrl: 'https://example.com/logo.png',
  rectangleLogo: 'https://example.com/rectangle-logo.png',
  heroImage: 'https://example.com/hero.png',
  googleHeroImage: 'https://example.com/google-hero.png',
  appleHeroImage: 'https://example.com/apple-hero.png',
  hexBackgroundColor: '#FF5733',
  appleFontColor: '#FFFFFF',
  textModulesData: [
    {
      id: 'phone',
      header: 'Phone',
      body: '+1 555-0123'
    }
  ],
  linksModuleData: [
    {
      id: 'website',
      description: 'Visit Website',
      uri: 'https://example.com'
    }
  ],
  barcodeType: 'QR_CODE',
  barcodeValue: 'https://example.com',
  barcodeAltText: 'Scan for more info'
}

Examples

This package includes complete example applications to help you get started:

• Next.js Example (example_apps/wallet-pass-app/) - A modern React/Next.js web application with a beautiful UI for creating and managing wallet passes
• Node.js Server Example (example_apps/node-server-example/) - A simple Express.js server with a web interface demonstrating all API operations

Both examples include:

• Complete setup instructions
• API key configuration
• Web-based UI for testing
• Real-time credit monitoring
• Comprehensive error handling

Notes

• Do not embed your secret API key in client code. Use getAuthToken.
• Pass URLs follow the format: https://app.addtowallet.co/card/{cardId}
• For complete API documentation and response shapes, refer to the official docs: AddToWallet API Docs.
• All API requests require authentication using an API key in the apikey header.
• Image uploads support JPG, PNG, and WebP formats with a maximum file size of 5MB.