🆘 Help Center

WalletForge is a comprehensive platform for creating, distributing, and managing Apple Wallet passes without coding. It's perfect for businesses that want to:

• Create digital loyalty cards, event tickets, coupons, and membership cards
• Send passes directly to customers via email or SMS
• Track pass usage and redemptions
• Manage customer databases
• Analyze distribution and engagement metrics

Step 1: Open WalletForge

1. Go to https://walletforge.io/dashboard.html
2. Click the "Create New Pass" button

Step 2: Fill in Basic Information

1. Pass Title - The main text on your pass (e.g., "VIP Member")
2. Description - Optional subtitle (e.g., "Gold Tier")
3. Organization Name - Your business name

Step 3: Customize Appearance

1. Click the Background Color picker
2. Choose your brand color
3. Upload your logo (optional, 2MB max)

Step 4: Add Custom Fields

1. Click "+ Add Field"
2. Enter Label (e.g., "Member ID") and Value (e.g., "12345")
3. Add as many fields as you need

Step 5: Add Barcode (Optional)

1. Select barcode type (QR Code recommended)
2. Enter barcode message (e.g., unique ID)

Step 6: Generate Pass

1. Review the preview on the right
2. Click "Generate Pass"
3. Your pass is now saved!

Available Templates

• Loyalty Card - For coffee shops, restaurants, retail stores
• Event Ticket - Concerts, conferences, sports events
• Membership Card - Gyms, clubs, associations
• Coupon - Discounts, promotions, special offers
• Boarding Pass - Airlines, buses, trains

How to Use a Template

1. Click "Templates" on the home screen
2. Browse available templates
3. Click on a template to apply it
4. All fields are pre-filled with sample data
5. Customize the values for your business
6. Click "Generate Pass"

Viewing Your Passes

1. Click "My Passes" on the home screen
2. See all your created passes in a grid
3. Each pass shows title, organization, and creation date

Pass Actions

Click on any pass to access these options:

• View - See full pass details
• Edit - Modify pass content
• Duplicate - Create a copy
• Share - Share via social media or link
• Download - Get .pkpass file
• Delete - Remove permanently

Storage Location

Passes are stored in two places:

• Browser - LocalStorage (fast access)
• Server - /passes/ folder (.pkpass files)

What is a .pkpass file?

A .pkpass file is the standard format for Apple Wallet passes. When you open it on an iPhone or iPad, it automatically opens the Wallet app.

How to Download

1. Open "My Passes"
2. Click on a pass
3. Click "Download .pkpass"
4. File is saved to your Downloads folder

Adding to Apple Wallet (iPhone/iPad)

1. Email the .pkpass file to yourself
2. Open email on your iPhone
3. Tap the .pkpass attachment
4. Tap "Add" in the top-right
5. Pass is now in your Wallet!

Real-Time Preview

As you edit your pass, the preview on the right updates instantly. This shows exactly how your pass will look in Apple Wallet.

Preview Elements

• Logo - Appears in top-left (if uploaded)
• Organization Name - Top-right corner
• Pass Title - Large text in center
• Description - Subtitle below title
• Custom Fields - Label-value pairs
• Barcode - Bottom of pass (if added)

Colors

The preview shows your chosen:

• Background Color - Pass background
• Text Color - All text elements

Edit Mode

1. Go to "My Passes"
2. Click on the pass you want to edit
3. Click "Edit" button
4. Form opens with current values
5. Make your changes
6. Click "Update Pass"

What You Can Edit

• Title and description
• Organization name
• Colors (background and text)
• Logo image
• Custom fields (add, remove, or modify)
• Barcode settings

What Happens to Distributed Passes?

How to Delete

1. Open "My Passes"
2. Click on the pass to delete
3. Click "Delete" button
4. Confirm deletion in the popup
5. Pass is permanently removed

What Gets Deleted

• Pass data from database
• .pkpass file from server
• All associated metadata

Distributed Passes

Deleting a pass from WalletForge does NOT remove it from customers' Apple Wallets. Once distributed, passes remain on their devices unless they manually delete them.

Color Psychology

Colors convey meaning and emotion:

• Blue - Trust, professionalism (banks, healthcare)
• Red - Energy, urgency (sales, restaurants)
• Green - Growth, eco-friendly (organic, wellness)
• Purple - Luxury, creativity (premium brands)
• Orange - Friendly, fun (entertainment, youth)
• Black - Elegance, sophistication (luxury, fashion)

Contrast is Key

Ensure text is readable:

• Light backgrounds → Use dark text
• Dark backgrounds → Use white/light text
• Test readability in bright sunlight and dark rooms

Brand Consistency

• Use your existing brand colors
• Match your website, logo, and marketing materials
• Create a consistent customer experience

Logo Requirements

• Format: PNG, JPG, GIF, or WebP
• Size: Maximum 2MB
• Recommended dimensions: 160x50 pixels
• Background: Transparent PNG works best

How to Upload

1. Click "Upload Logo" button
2. Select your logo file
3. Image appears in preview
4. Logo shows in top-left of pass

Optimization Tips

• Use simple, clear logos (complex details may not show well)
• Avoid text-heavy logos (hard to read at small size)
• Test with both light and dark backgrounds
• Compress images to reduce file size

Removing Logos

To remove a logo, click the "Remove Logo" button that appears after upload.

What Are Custom Fields?

Custom fields are label-value pairs that display information on your pass. Examples:

• Label: "Member ID" | Value: "12345"
• Label: "Expires" | Value: "Dec 31, 2025"
• Label: "Points" | Value: "1,250"

Adding Fields

1. Click "+ Add Field"
2. Enter label in left input
3. Enter value in right input
4. Field appears in preview
5. Add unlimited fields

Removing Fields

Click the "-" button next to any field to remove it.

Field Ideas by Pass Type

Loyalty Cards:

• Points Balance
• Member Since
• Tier Level

Event Tickets:

• Event Date
• Venue
• Seat Number
• Doors Open

Coupons:

• Discount Amount
• Expiration Date
• Terms & Conditions

Available Formats

• QR Code - Most common, works with any QR scanner
• PDF417 - Used for airline boarding passes
• Aztec - Compact, used for tickets
• Code 128 - Traditional barcode, retail use

QR Code (Recommended)

Best for:

• Loyalty cards
• Event tickets
• Coupons and vouchers
• Any pass that needs scanning

Why? Universal compatibility, can store more data, works with any smartphone camera

What to Put in Barcode Message

• Unique ID: "PASS-2024-001234"
• Customer ID: "CUST-789456"
• URL: "https://yoursite.com/validate/abc123"
• Any text: Will be encoded in barcode

No Barcode Needed?

Leave the barcode section empty if you don't need scanning functionality. This is fine for informational passes.

Keep It Simple

• Don't overcrowd with too many fields
• Use 3-5 custom fields maximum
• Focus on essential information

Readability First

• High contrast between text and background
• Large, clear fonts (handled automatically)
• Short, concise text

Brand Consistency

• Use official brand colors
• Include your logo
• Match your other marketing materials

Test on Real Devices

• View on iPhone/iPad before mass distribution
• Check readability in different lighting
• Verify barcode scans correctly

Pass Type Guidelines

Loyalty Cards:

• Prominent logo
• Clear member ID or points
• Brand colors

Event Tickets:

• Event name in title
• Date, time, venue in fields
• QR code for entry

Coupons:

• Discount amount in title
• Expiration date visible
• Eye-catching colors

When to Duplicate

• Creating similar passes for different customers
• Making seasonal variations (Summer/Winter)
• Testing design changes
• Creating tier levels (Bronze/Silver/Gold)

How to Duplicate

1. Go to "My Passes"
2. Click on the pass to duplicate
3. Click "Duplicate" button
4. Copy is created with " - Copy" in the title
5. Edit the copy as needed

What Gets Copied

• All text content
• Colors and design
• Logo image
• Custom fields
• Barcode settings

What Changes

• Pass ID (new unique identifier)
• Creation date
• Title (appends " - Copy")

Step-by-Step

1. Go to https://walletforge.io/customers.html
2. Click "+ Add Customer" button
3. Fill in the form:
   • First Name (required)
   • Last Name (required)
   • Email (required)
   • Phone (optional, format: +1234567890)
   • Company (optional)
   • Notes (optional, internal use)
4. Click "Save Customer"
5. Customer appears in the list

Required Fields

Only 3 fields are mandatory:

• First Name
• Last Name
• Email (must be valid format)

Phone Number Format

For SMS distribution, use E.164 format:

• US: +1234567890
• UK: +441234567890
• Include country code with + prefix

How to Edit

1. Go to customers.html
2. Find the customer in the list
3. Click the ✏️ Edit button
4. Update form opens with current values
5. Make your changes
6. Click "Save Customer"

What You Can Edit

• Name (first and last)
• Email address
• Phone number
• Company name
• Notes

Email Change Warning

Search Function

1. Locate the search bar at top of customers.html
2. Type at least 2 characters
3. Press Enter or click "🔍 Search"
4. Results appear instantly

What You Can Search

The search looks in these fields:

• First Name
• Last Name
• Email
• Phone Number
• Company Name

Search Tips

• Partial matches work (search "john" finds "Johnson")
• Case insensitive (JOHN = john = John)
• Returns up to 50 results
• Click "Clear" to see all customers again

Examples

• john - Finds all Johns, Johnsons, etc.
• @gmail - Finds all Gmail customers
• 555 - Finds phone numbers containing 555
• acme - Finds customers from Acme company

How to Delete

1. Find customer in the list
2. Click the 🗑️ Delete button
3. Confirm deletion in popup
4. Customer is permanently removed

What Gets Deleted

• Customer record from database
• All distribution history for that customer
• All redemption records linked to that customer

Effect on Distributed Passes

Deleting a customer does NOT:

• Remove passes from their Apple Wallet
• Cancel any active passes they have
• Prevent them from using existing passes

When to Delete

• Customer requests data removal (GDPR)
• Duplicate entries
• Test customers
• Inactive customers (per your policy)

Dashboard Stats

At the top of customers.html, you'll see:

• Total Customers - All customers in database
• New This Month - Customers added this month
• Total Distributions - Passes sent to all customers
• Email Sent - Emails distributed

Detailed Statistics API

Access via: api/customers.php?action=stats

Returns JSON with:

• Total customer count
• New customers this month
• Distribution breakdown by type (email/SMS/bulk)

Using Stats for Business Decisions

• Track customer growth over time
• Identify popular distribution methods
• Monitor campaign effectiveness
• Plan capacity and resources

How Pagination Works

• Shows 20 customers per page by default
• Page numbers appear at bottom
• Click number to jump to that page
• Use "Previous" and "Next" buttons

Large Databases

For databases with hundreds or thousands of customers:

• Pages show as: 1 2 3 ... 10
• Current page is highlighted
• Quick jump to first/last page
• Use search to find specific customers faster

Performance

Pagination ensures fast loading even with 10,000+ customers by only loading 20 at a time.

Notes Field

Use notes for:

• Internal reminders
• Customer preferences
• Special instructions
• Account status

Examples:

• "VIP customer - priority support"
• "Prefers SMS over email"
• "Birthday: March 15"
• "Referred by John Smith"

Tags (Future Feature)

The database supports tags for categorization:

• VIP
• New Customer
• High Value
• Email Only

Overview

Bulk Create is a PRO feature that allows you to generate multiple Apple Wallet passes from a single CSV file or pasted spreadsheet data. Perfect for:

• Membership Programs - Create passes for all members at once
• Event Tickets - Generate tickets for attendee lists
• Loyalty Cards - Issue cards to existing customers
• Gift Cards - Bulk create promotional passes

How It Works

1. Choose an existing pass as your template (design & layout)
2. Upload CSV or paste data with customer information
3. Map CSV columns to pass fields (auto-detected)
4. Generate - creates one pass per row

Key Benefits

• Save hours vs creating passes one-by-one
• Consistent design across all passes
• Personalized data for each recipient
• Track batches and review success/failure rates

CSV Structure

Your CSV file should have:

• Header Row - Column names in first row
• Data Rows - One row per pass to create
• Consistent Columns - Same fields in every row

Sample CSV

Name,Email,MemberID,Points,ExpirationDate,BarcodeValue
John Doe,john@example.com,M001,1250,2025-12-31,BARCODE001
Jane Smith,jane@example.com,M002,2340,2025-12-31,BARCODE002
Bob Johnson,bob@example.com,M003,890,2025-12-31,BARCODE003

Recommended Columns

Column Name	Purpose	Example
Name	Member/customer name	John Doe
Email	Email address	john@example.com
MemberID	Unique identifier	M12345
Points	Loyalty points/balance	1250
ExpirationDate	Pass expiry	2025-12-31
BarcodeValue	QR/barcode data	BARCODE001

Creating CSV from Excel/Google Sheets

1. Open your spreadsheet
2. Ensure first row has column headers
3. Excel: File → Save As → CSV (Comma delimited)
4. Google Sheets: File → Download → Comma-separated values (.csv)

Step 1: Choose Your Template

1. Click "Bulk Create Passes" from dashboard
2. Select an existing pass as your template
3. Template provides: design, colors, logo, layout
4. CSV will override: names, IDs, barcodes, custom fields
5. Click "Next: Upload Data"

Step 2: Upload Your Data

Choose upload method:

Option A: Upload CSV File

1. Click "Upload CSV" tab
2. Drag & drop file or click to browse
3. Select your .csv file
4. Preview shows first 5 rows
5. Verify data looks correct

Option B: Paste Data

1. Click "Paste Data" tab
2. Copy rows from Excel/Sheets (Ctrl+C)
3. Paste into text area (Ctrl+V)
4. Click "Parse Data"
5. Preview appears automatically

Click "Next: Map Fields" when ready

Step 3: Map Your Columns

1. System auto-detects common mappings
2. Review each mapping dropdown
3. Change any incorrect mappings
4. Leave unmapped if column not needed
5. Mappings available:
   • Pass Title (Main Text)
   • Description (Subtitle)
   • Member Name
   • Member ID
   • Points / Balance
   • Expiration Date
   • Barcode/QR Value
   • Custom Fields 1-3 (Label & Value)
6. Click "Next: Review & Generate"

Step 4: Review & Generate

1. Review summary:
   • Template name
   • Total rows to process
   • Mapped fields count
2. Click "🚀 Generate Passes"
3. Progress bar shows creation status
4. Wait for completion (large batches take longer)
5. Results screen shows success/failure stats

After Generation

• View success/failure counts
• Export failed rows if any
• Click "View All Passes" to see created passes
• All passes tagged with batch ID

What is Column Mapping?

Column mapping tells WalletForge which CSV column corresponds to which pass field. This allows flexible CSV formats.

Auto-Detection

The system automatically detects these column names:

• Name, Member Name, Full Name → Member Name
• MemberID, Member ID, ID → Member ID
• Points, Balance → Points/Balance
• Expiration, Expiration Date, Expires → Expiration Date
• Barcode, QR, Code → Barcode Value
• Title, Pass Title → Pass Title

Manual Mapping

If auto-detection doesn't match your columns:

1. Find the pass field you want to populate
2. Use the dropdown to select correct CSV column
3. Select "-- Skip this field --" to leave unmapped

Custom Fields

For dynamic custom fields:

• Map both Label and Value for each custom field
• Example:
  • Custom Field 1 Label → "Tier"
  • Custom Field 1 Value → "Gold"
• Up to 3 custom fields supported

Unmapped Columns

CSV columns you don't map are simply ignored. This is useful when your CSV has extra data you don't need on the passes.

Failed Rows

Problem: Some rows failed to generate

Causes & Solutions:

• Invalid Date Format - Use YYYY-MM-DD format (2025-12-31)
• Missing Required Field - Check all mapped required fields have values
• Duplicate Barcode - Ensure each barcode value is unique
• Special Characters - Remove or escape quotes, commas in data

Fix:

1. Click "Export Failed Rows"
2. Open exported CSV
3. Fix errors in spreadsheet
4. Re-run bulk create with corrected rows only

CSV Won't Upload

Problem: File upload fails or shows errors

Solutions:

• Ensure file extension is .csv
• Save as "CSV (Comma delimited)" not "CSV UTF-8"
• Check file size (max 5MB recommended)
• Remove empty rows at bottom of spreadsheet
• Ensure header row is present

Wrong Data in Passes

Problem: Passes created but data is incorrect

Solution:

1. Delete incorrectly created passes
2. Review column mappings in Step 3
3. Verify CSV data preview matches expectations
4. Test with 2-3 rows first
5. Regenerate after confirming mappings

Slow Generation

Problem: Bulk create takes very long

Normal Behavior:

• ~100 passes: 5-10 seconds
• ~500 passes: 30-60 seconds
• ~1000 passes: 1-2 minutes

Tips:

• Don't close browser during generation
• Split very large batches (1000+) into smaller chunks
• Clear browser cache if extremely slow

Can't Find Generated Passes

Solution:

1. Go to "My Passes"
2. All bulk-created passes have same creation timestamp
3. Sort by "Date Created" to see batch together
4. Each pass stores batch ID in metadata