ghostguild-org/HELCIM_TICKET_INTEGRATION.md

Helcim Event Ticketing Integration - Implementation Summary

Overview

Successfully integrated Helcim payment processing with Ghost Guild's event ticketing system to support paid events, member pricing, early bird discounts, and capacity management.

What Was Built

1. Enhanced Event Model (server/models/event.js)

Added comprehensive ticket schema with:

• Member tickets: Free/discounted pricing for members with circle-specific overrides
• Public tickets: Standard pricing with early bird support
• Capacity management: Overall event capacity tracking
• Waitlist system: Queue management when events sell out
• Registration tracking: Enhanced with ticket type, price paid, payment status, and refund info

2. Ticket Business Logic (server/utils/tickets.js)

Created utility functions for:

• calculateTicketPrice() - Determines applicable price based on member status and early bird
• checkTicketAvailability() - Real-time availability checking
• validateTicketPurchase() - Pre-purchase validation
• reserveTicket() - Temporary reservation during checkout (prevents race conditions)
• releaseTicket() - Release abandoned reservations
• completeTicketPurchase() - Finalize purchase and update counts
• addToWaitlist() - Waitlist management
• formatPrice() - Consistent price formatting

3. API Endpoints (server/api/events/[id]/tickets/)

Four new REST endpoints:

GET available.get.js

• Check ticket availability and pricing for a user
• Returns: ticket type, price, availability, remaining spots
• Supports both authenticated (members) and public users

POST check-eligibility.post.js

• Verify if user qualifies for member pricing
• Returns: member status and circle information

POST purchase.post.js

• Complete ticket purchase with Helcim payment
• Validates availability, processes payment, creates registration
• Handles both free (member) and paid (public) tickets

POST reserve.post.js

• Temporarily reserve ticket during checkout
• Prevents overselling during payment processing
• 10-minute TTL on reservations

4. Frontend Components

EventTicketCard.vue

Reusable ticket display component showing:

• Ticket name and description
• Price with early bird indicator
• Member savings comparison
• Availability status
• Waitlist option when sold out

EventTicketPurchase.vue

Main ticket purchase flow component:

• Fetches ticket availability on load
• Displays appropriate ticket card
• Registration form (name, email)
• Integrated Helcim payment for paid tickets
• Success/error handling with toast notifications
• Shows "already registered" state

5. Enhanced Composable (app/composables/useHelcimPay.js)

Added initializeTicketPayment() method:

• Ticket-specific payment initialization
• Includes event metadata for tracking
• Uses email as customer code for one-time purchases

6. Updated Event Detail Page (app/pages/events/[id].vue)

• Detects if event has tickets enabled
• Shows new ticket system OR legacy registration form
• Maintains backward compatibility
• Handles ticket purchase success/error events

7. Enhanced Email Templates (server/utils/resend.js)

Updated registration confirmation emails to include:

• Ticket type (Member/Public)
• Amount paid
• Transaction ID
• "Member Benefit" callout for free member tickets

How It Works

Free Member Event Flow

1. Member views event → Sees "Free for Members" ticket
2. Fills in name/email → Click "Complete Registration"
3. System verifies membership → Creates registration
4. Sends confirmation email → Shows success message

Paid Public Event Flow

1. Public user views event → Sees ticket price
2. Fills in name/email → Clicks "Pay $XX.XX"
3. Helcim modal opens → User enters payment info
4. Payment processes → System creates registration
5. Sends confirmation with receipt → Shows success

Early Bird Pricing

- Before deadline: Shows early bird price + countdown
- After deadline: Automatically switches to regular price
- Calculated server-side for security

Configuration

Event Setup

To enable ticketing for an event, set in the event document:

{
  tickets: {
    enabled: true,
    currency: "CAD",
    member: {
      available: true,
      isFree: true,  // or set price
      name: "Member Ticket",
      description: "Free for Ghost Guild members"
    },
    public: {
      available: true,
      price: 25.00,
      quantity: 50,  // or null for unlimited
      earlyBirdPrice: 20.00,
      earlyBirdDeadline: "2025-11-01T00:00:00Z",
      name: "Public Ticket"
    },
    capacity: {
      total: 75  // Total capacity across all ticket types
    }
  }
}

Circle-Specific Pricing Example

{
  tickets: {
    member: {
      isFree: false,  // Not free by default
      price: 15.00,   // Default member price
      circleOverrides: {
        community: {
          isFree: true  // Free for community circle
        },
        founder: {
          price: 10.00  // Discounted for founders
        },
        practitioner: {
          price: 5.00  // Heavily discounted for practitioners
        }
      }
    }
  }
}

Migration Strategy

Backward Compatibility

• Legacy pricing field still supported
• Events without tickets.enabled use old registration system
• Existing registrations work with new system

Converting Events to New System

// Old format
{
  pricing: {
    isFree: false,
    publicPrice: 25,
    paymentRequired: true
  }
}

// New format
{
  tickets: {
    enabled: true,
    member: {
      isFree: true
    },
    public: {
      available: true,
      price: 25
    }
  }
}

Testing Checklist

Member Ticket Flow

• Member can see free ticket
• Email pre-fills if logged in
• Registration completes without payment
• Confirmation email shows member benefit
• "Already registered" state shows correctly

Public Ticket Flow

• Public user sees correct price
• Helcim modal opens on submit
• Payment processes successfully
• Transaction ID saved to registration
• Confirmation email includes receipt

Early Bird Pricing

• Early bird price shows before deadline
• Countdown timer displays correctly
• Regular price shows after deadline
• Price calculation is server-side

Capacity Management

• Ticket count decrements on purchase
• Sold out message shows when full
• Waitlist option appears if enabled
• No overselling (test concurrent purchases)

Edge Cases

• Already registered users see status
• Cancelled events show cancellation message
• Past events don't allow registration
• Member-only events gate non-members
• Payment failures don't create registrations

Future Enhancements

Phase 2 Features

1. Waitlist Notifications: Auto-email when spots open
2. Refund Processing: Handle ticket cancellations with refunds
3. Ticket Types: Multiple ticket tiers per event
4. Group Tickets: Purchase multiple tickets at once
5. Promo Codes: Discount code support
6. Admin Dashboard: View sales, export attendee lists

Phase 3 Features

1. Recurring Events: Auto-apply tickets to series
2. Transfer Tickets: Allow users to transfer registrations
3. PDF Tickets: Generate printable/QR code tickets
4. Revenue Analytics: Track ticket sales and revenue
5. Dynamic Pricing: Adjust prices based on demand

Files Created

• server/utils/tickets.js (420 lines)
• server/api/events/[id]/tickets/available.get.js (150 lines)
• server/api/events/[id]/tickets/purchase.post.js (180 lines)
• server/api/events/[id]/tickets/check-eligibility.post.js (50 lines)
• server/api/events/[id]/tickets/reserve.post.js (80 lines)
• app/components/EventTicketCard.vue (195 lines)
• app/components/EventTicketPurchase.vue (330 lines)

Files Modified

• server/models/event.js - Enhanced ticket schema + registration fields
• app/pages/events/[id].vue - Integrated ticket UI
• app/composables/useHelcimPay.js - Added ticket payment method
• server/utils/resend.js - Enhanced email with ticket info

Total Implementation

• ~1,400 lines of code across 11 files
• 4 new API endpoints
• 2 new Vue components
• 10+ utility functions
• Fully backward compatible

Support

For questions or issues:

• Check Helcim API docs: https://docs.helcim.com
• Review CLAUDE.md for project context
• Test in development with Helcim test credentials

---

Status: ✅ Implementation Complete Last Updated: 2025-10-14 Developer: Claude (Anthropic)