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)
```javascript
{
  tickets: {
    enabled: false  // Use legacy registration system
  }
  // OR
  tickets: {
    enabled: true,
    member: { isFree: true },
    public: { available: true, price: 0 }
  }
}
```

### 2. Members Only, Free
```javascript
{
  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
```javascript
{
  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
```javascript
{
  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
```javascript
{
  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
```javascript
{
  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
```javascript
{
  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.