Core Concepts

Before diving into the API, it's helpful to understand WalletWerk's data model and how the pieces fit together.

Data Model

WalletWerk organizes wallet cards in a hierarchical structure:

• Organization: Your WalletWerk account (one organization per account)
• Campaigns: Top-level containers that define card design, shared data, and settings
• Recipients: People who receive wallet cards (always associated with a campaign)
• Wallet Cards: The actual cards that end up in users' wallets
• Provider Objects: Platform-specific instances (Apple Wallet, Google Wallet, EUDIW)

Campaigns

A Campaign is the top-level container for your wallet card program. Think of it as a "template" that defines:

• Card design — colors, images, branding
• Shared data — event details, venue, dates, terms
• Target providers — Apple Wallet, Google Wallet, or both
• Lifecycle dates — start and end dates

Campaigns are typically created once and then populated with recipients. When you update a campaign (e.g., change the venue), those changes automatically propagate to all active wallet cards.

Campaign Types

Barcodes

Wallet cards can include a barcode for scanning/validation. The barcode type and value are configured per campaign.

Barcode Types

Barcode Value Strategies

Setting Barcode Type:

Set the barcode type in campaignData when creating or updating a campaign:

{
  "campaignData": {
    "barcodeType": "qr",
    "barcodeValueStrategy": "auto"
  }
}

Custom Barcode Values:

When using barcodeValueStrategy: "custom", provide the barcode value in the recipient's recipientData:

{
  "email": "john@example.com",
  "name": "John Doe",
  "recipientData": {
    "barcodeValue": "TICKET-12345-ABC"
  }
}

Recipients

A Recipient represents a person who will receive a wallet card. Recipients are always associated with a campaign and can have:

• Contact info — email (required), name, phone
• External ID — your internal user/customer ID for syncing
• Recipient data — individual overrides (seat number, ticket tier, etc.)

When you add a recipient to a campaign, WalletWerk automatically:

1. Creates a wallet card combining campaign + recipient data
2. Generates download URLs for each enabled provider
3. Optionally sends an invite email

Recipient Invitation Flow

Recipients are created with status "pending". To invite them:

1. Create recipient → Status: "pending" (no wallet card yet)
2. Call /invite endpoint → Wallet card created → Status: "invited" → Email sent (if sendEmail: true)

The invitation process is explicit and separate from creation. You must call the /invite endpoint to:

• Create the wallet card
• Mark recipient as "invited"
• Send email (optional, with customizable content)

Wallet Cards

A Wallet Card is the actual card that ends up in someone's Apple Wallet or Google Wallet. Each card:

• Belongs to one campaign
• Is linked to one recipient
• Has one or more provider objects (Apple, Google, EUDIW)
• Tracks its own lifecycle status

Cards are created automatically when you add recipients. You don't need to create them manually.

Wallet Card Lifecycle

Understanding the card lifecycle helps you track engagement and troubleshoot issues.

Status Flow

pending → created → invited → active ↓ revoked / removed / deleted

Status Values

Status Transitions

Callbacks from Wallet Providers

Apple and Google send callbacks when users interact with cards. WalletWerk automatically updates status based on these callbacks:

You can poll the /status endpoint to check the current status, or subscribe to webhooks for real-time updates.

Real-time Updates

One of WalletWerk's key features is live updates. When you modify a campaign or recipient, changes propagate to all active cards.

What Gets Updated

How It Works

1. You call PATCH /campaigns/{id} or PATCH /recipients/{id}
2. WalletWerk finds all active cards affected
3. Card data is updated in our system
4. For Apple: Cards update on next wallet sync (usually minutes)
5. For Google: Cards update immediately

Push Notifications

You can send push notifications to users with active cards:

Notifications appear on the user's lock screen, linked to their wallet card.