ghostguild-org/docs/TICKET_SETUP_GUIDE.md

Event Ticket Setup Guide

Quick reference for creating events with different ticket configurations.

Common Scenarios

1. Free Event (Everyone)

{
  tickets: {
    enabled: false  // Use legacy registration system
  }
  // OR
  tickets: {
    enabled: true,
    member: { isFree: true },
    public: { available: true, price: 0 }
  }
}

2. Members Only, Free

{
  membersOnly: true,
  tickets: {
    enabled: true,
    member: {
      available: true,
      isFree: true,
      name: "Member Ticket",
      description: "Free for all Ghost Guild members"
    },
    public: {
      available: false  // No public tickets
    }
  }
}

3. Free for Members, Paid for Public

{
  tickets: {
    enabled: true,
    currency: "CAD",
    member: {
      available: true,
      isFree: true,
      name: "Member Ticket"
    },
    public: {
      available: true,
      name: "Public Ticket",
      price: 25.00,
      quantity: 30,  // Limit public tickets
      description: "General admission for non-members"
    },
    capacity: {
      total: 50  // 20 spots reserved for members
    }
  }
}

4. Early Bird Pricing

{
  tickets: {
    enabled: true,
    member: { isFree: true },
    public: {
      available: true,
      price: 30.00,           // Regular price
      earlyBirdPrice: 22.00,  // Discounted price
      earlyBirdDeadline: "2025-11-15T23:59:59Z",
      quantity: 50
    }
  }
}

5. Tiered Member Pricing

{
  tickets: {
    enabled: true,
    member: {
      available: true,
      isFree: false,
      price: 15.00,  // Default member price
      circleOverrides: {
        community: {
          isFree: true  // Community members get in free
        },
        founder: {
          price: 10.00  // Founder discount
        },
        practitioner: {
          price: 10.00  // Practitioner discount
        }
      }
    },
    public: {
      available: true,
      price: 35.00
    }
  }
}

6. Waitlist Enabled

{
  tickets: {
    enabled: true,
    member: { isFree: true },
    public: {
      available: true,
      price: 20.00,
      quantity: 25  // Limited capacity
    },
    capacity: {
      total: 40
    },
    waitlist: {
      enabled: true,
      maxSize: 20  // Or null for unlimited
    }
  }
}

Field Reference

tickets.enabled

• Type: Boolean
• Default: false
• Purpose: Enable new ticket system (vs. legacy registration)

tickets.currency

• Type: String
• Default: "CAD"
• Options: ISO currency codes (CAD, USD, etc.)

tickets.member.*

Configuration for member tickets

• available (Boolean) - Members can register
• isFree (Boolean) - Free for members
• price (Number) - Price if not free
• name (String) - Display name
• description (String) - Additional details
• circleOverrides (Object) - Circle-specific pricing

tickets.public.*

Configuration for public (non-member) tickets

• available (Boolean) - Public can register
• name (String) - Display name
• description (String) - Additional details
• price (Number) - Regular price
• quantity (Number) - Max tickets (null = unlimited)
• sold (Number) - Counter (auto-managed)
• reserved (Number) - Temp reservations (auto-managed)
• earlyBirdPrice (Number) - Early bird discount price
• earlyBirdDeadline (Date) - When early bird ends

tickets.capacity.*

Overall event capacity

• total (Number) - Max attendees across all types
• reserved (Number) - Currently reserved (auto-managed)

tickets.waitlist.*

Waitlist configuration

• enabled (Boolean) - Allow waitlist
• maxSize (Number) - Max waitlist size (null = unlimited)
• entries (Array) - Waitlist entries (auto-managed)

Tips

Capacity Planning

• Set capacity.total for overall limit
• Set public.quantity to reserve spots for members
• Example: 50 total capacity, 30 public tickets = 20 spots for members

Early Bird Strategy

• Set deadline 1-2 weeks before event
• Discount 20-30% off regular price
• Creates urgency and rewards early commitment

Member Value

• Always offer member benefit (free or discounted)
• Show savings in ticket card
• Reinforces membership value proposition

Pricing Psychology

• Round numbers: $25 instead of $24.99
• Early bird: Show regular price crossed out
• Member comparison: Display public price for context

Testing Events

Test Mode Configuration

{
  title: "TEST - Ticket System Demo",
  tickets: {
    enabled: true,
    member: {
      isFree: true,
      description: "Testing member flow"
    },
    public: {
      available: true,
      price: 0.50,  // Low price for testing
      quantity: 5,   // Small capacity for testing
      description: "Testing payment flow"
    }
  }
}

Test Cards (Helcim)

Use Helcim's test card numbers in test mode:

• Visa: 4242 4242 4242 4242
• Mastercard: 5555 5555 5555 4444
• Declined: 4000 0000 0000 0002

Common Gotchas

1. Forgot to enable tickets: Set tickets.enabled: true
2. Members can't register: Check tickets.member.available: true
3. Payment not processing: Verify Helcim credentials in .env
4. Early bird not showing: Check deadline hasn't passed
5. Capacity exceeded: Check both capacity.total and public.quantity

Support

If tickets aren't working:

1. Check server logs for errors
2. Verify Helcim API credentials
3. Test with free event first
4. Review event document in MongoDB
5. Check browser console for frontend errors

---

Need help? Review HELCIM_TICKET_INTEGRATION.md for full implementation details.