Organizer Analytics API

Author: Josh, Lead Backend Team
Last Updated: 2025-12-11
Version: v1.0

Base URL: https://api.nexgate.com/api/v1

Short Description: The Organizer Analytics API provides comprehensive financial and performance insights for event organizers. This API enables organizers to track total collections across all events, analyze revenue by event with filters, monitor individual event performance with detailed metrics, and visualize revenue trends over time with monthly/yearly breakdowns. The system calculates escrow holdings, released payments, ticket sales, attendance rates, and sell-out percentages automatically.

Hints:

Organizer Only: All endpoints restricted to event organizers
Auto-Calculations: Revenue, attendance, sell-out rates computed automatically
Escrow Tracking: Separate tracking for held vs released funds
Multi-Event: Aggregates data across all organizer's events
Time Filters: Filter by status, date range, year
Pagination: Event lists paginated (default 20 per page)
Top Performer: Identifies highest revenue event
Trend Analysis: Monthly/yearly revenue patterns
Real-Time: Updates reflect latest bookings and check-ins

Response Structures

CollectionSummaryResponse

{
  "eventMetrics": {
    "totalEvents": 15,
    "upcomingEvents": 5,
    "ongoingEvents": 1,
    "completedEvents": 8,
    "cancelledEvents": 1
  },
  "collectionMetrics": {
    "totalTicketsSold": 2500,
    "totalRevenue": 5000000.00,
    "inEscrow": 1200000.00,
    "released": 3800000.00,
    "refunded": 0.00,
    "pendingRefunds": 0.00
  },
  "topEvent": {
    "eventId": "uuid",
    "eventTitle": "East African Tech Summit 2025",
    "revenue": 1500000.00,
    "ticketsSold": 500,
    "attendanceRate": 92.5
  }
}

EventRevenueResponse

{
  "events": [
    {
      "eventId": "uuid",
      "eventTitle": "East African Tech Summit 2025",
      "eventDate": "2025-12-15T09:00:00",
      "status": "PUBLISHED",
      "ticketsSold": 500,
      "totalRevenue": 1500000.00,
      "inEscrow": 1500000.00,
      "released": 0.00,
      "refunded": 0.00,
      "attendanceRate": 0.0,
      "totalCapacity": 1000,
      "sellOutPercentage": 50.0
    }
  ],
  "pagination": {
    "currentPage": 0,
    "pageSize": 20,
    "totalPages": 3,
    "totalElements": 45,
    "hasNext": true,
    "hasPrevious": false
  }
}

EventPerformanceResponse

{
  "eventId": "uuid",
  "eventTitle": "East African Tech Summit 2025",
  "eventDate": "2025-12-15T09:00:00",
  "status": "COMPLETED",
  "financials": {
    "totalRevenue": 1500000.00,
    "inEscrow": 0.00,
    "released": 1500000.00,
    "refunded": 0.00,
    "averageTicketPrice": 3000.00
  },
  "ticketMetrics": {
    "totalCapacity": 1000,
    "totalSold": 500,
    "totalRemaining": 500,
    "sellOutPercentage": 50.0
  },
  "attendanceMetrics": {
    "totalTickets": 500,
    "checkedIn": 462,
    "noShows": 38,
    "attendanceRate": 92.4
  },
  "timeline": {
    "createdAt": "2025-10-01T10:00:00",
    "publishedAt": "2025-10-05T14:30:00",
    "firstSaleAt": "2025-10-06T09:15:00",
    "eventDate": "2025-12-15T09:00:00",
    "completedAt": "2025-12-15T18:00:00"
  }
}

RevenueTrendResponse

{
  "period": "MONTHLY",
  "totalEvents": 12,
  "trends": [
    {
      "label": "JAN",
      "year": 2025,
      "month": 1,
      "eventsCount": 2,
      "ticketsSold": 350,
      "revenue": 875000.00,
      "inEscrow": 0.00,
      "released": 875000.00,
      "averageAttendanceRate": 88.5,
      "averageSellOutRate": 62.0
    }
  ]
}

Endpoints

1. Get Collection Summary

Endpoint: GET /analytics/collections/summary

Access: 🔒 Organizer Only

Success Response: Returns CollectionSummaryResponse

Success Response Message: "Collection summary retrieved"

Behavior:

Aggregates ALL organizer's events
Calculates escrow (PUBLISHED, HAPPENING events)
Calculates released (COMPLETED events)
Identifies top performer by revenue
Real-time metrics from latest data

Metrics Included:

Event counts by status
Total tickets sold
Total revenue (all time)
Money in escrow (upcoming/ongoing)
Money released (completed)
Refunds (placeholder)
Top performing event

2. Get Event Revenue

Endpoint: GET /analytics/collections/by-event?status=PUBLISHED&startDate=2025-01-01&endDate=2025-12-31&page=0&size=20

Access: 🔒 Organizer Only

Query Parameters:

Parameter	Type	Required	Description
status	string	No	Filter by event status (PUBLISHED, COMPLETED, etc.)
startDate	date (ISO)	No	Filter events from this date (2025-01-01)
endDate	date (ISO)	No	Filter events until this date (2025-12-31)
page	integer	No	Page number (0-indexed, default: 0)
size	integer	No	Items per page (default: 20)

Success Response: Returns EventRevenueResponse with pagination

Success Response Message: "Event revenue retrieved"

Behavior:

Lists organizer's events with revenue details
Filters by status and date range
Sorted by event date (newest first)
Paginated results
Includes capacity and sell-out metrics

3. Get Event Performance

Endpoint: GET /analytics/performance/{eventId}

Access: 🔒 Event Organizer Only

Path Parameters:

Parameter	Type	Required	Description
eventId	string (UUID)	Yes	Event identifier

Success Response: Returns EventPerformanceResponse

Success Response Message: "Event performance retrieved"

Behavior:

Validates organizer owns event
Calculates comprehensive metrics
Shows financial breakdown
Displays ticket sales vs capacity
Tracks attendance from check-ins
Provides event timeline

Metrics Sections:

Financials: Revenue, escrow, released, average price
Tickets: Capacity, sold, remaining, sell-out %
Attendance: Total, checked-in, no-shows, rate
Timeline: Key dates from creation to completion

Errors:

403 FORBIDDEN: Not event organizer
404 NOT_FOUND: Event not found

4. Get Revenue Trends

Endpoint: GET /analytics/trends?period=MONTHLY&year=2025

Access: 🔒 Organizer Only

Query Parameters:

Parameter	Type	Required	Description
period	string	No	MONTHLY or YEARLY (default: MONTHLY)
year	integer	No	Year to analyze (default: current year)

Success Response: Returns RevenueTrendResponse

Success Response Message: "Revenue trends retrieved"

Behavior:

MONTHLY Period:

Shows all 12 months for specified year
Data per month: events, tickets, revenue, escrow, released
Calculates average attendance and sell-out rates

YEARLY Period:

Shows all years organizer has events
Data per year: total events, tickets, revenue
Year-over-year comparison

Each Period Includes:

Event count
Tickets sold
Total revenue
Money in escrow
Money released
Average attendance rate
Average sell-out rate

Key Calculations

Escrow vs Released

In Escrow (Not yet paid to organizer):

PUBLISHED events (upcoming)
HAPPENING events (ongoing)
Formula: Sum of booking totals for non-completed events

Released (Paid to organizer):

COMPLETED events only
Formula: Sum of booking totals for completed events

Example:

Event A: PUBLISHED, Revenue: 500,000 TZS → In Escrow
Event B: HAPPENING, Revenue: 300,000 TZS → In Escrow  
Event C: COMPLETED, Revenue: 1,200,000 TZS → Released

Total Revenue: 2,000,000 TZS
In Escrow: 800,000 TZS
Released: 1,200,000 TZS

Attendance Rate

Attendance Rate = (Checked-In Tickets / Total Tickets) × 100

Example:

Total tickets: 500
Checked-in: 462
Attendance: 92.4%

Sell-Out Percentage

Sell-Out % = (Tickets Sold / Total Capacity) × 100

Example:

Capacity: 1000
Sold: 500
Sell-out: 50%

Average Ticket Price

Average Price = Total Revenue / Total Tickets

Example:

Revenue: 1,500,000 TZS
Tickets: 500
Average: 3,000 TZS

Event Status Flow

DRAFT → PUBLISHED → HAPPENING → COMPLETED
   ↓                               ↓
CANCELLED                     (Revenue Released)

Financial Impact by Status:

DRAFT: No bookings, no revenue
PUBLISHED: Bookings allowed, revenue in escrow
HAPPENING: Ongoing, revenue still in escrow
COMPLETED: Revenue released to organizer
CANCELLED: Refunds processed (if applicable)

Top Performer Logic

Selection Criteria: Highest total revenue

Metrics Included:

Event ID and title
Total revenue (highest wins)
Tickets sold
Attendance rate

Use Case: Dashboard highlight showing best-performing event

Use Cases

Dashboard Overview

GET /analytics/collections/summary

Shows:
- Total events across all statuses
- Total revenue (all time)
- Current escrow balance
- Released payments
- Top performing event

Event List with Filters

GET /analytics/collections/by-event?status=COMPLETED&page=0&size=20

Shows:
- All completed events
- Revenue details per event
- Attendance and sell-out rates
- Paginated for easy navigation

Deep Dive on Specific Event

GET /analytics/performance/550e8400-e29b-41d4-a716-446655440000

Shows:
- Complete financial breakdown
- Ticket sales metrics
- Attendance statistics
- Event timeline

Monthly Revenue Analysis

GET /analytics/trends?period=MONTHLY&year=2025

Shows:
- Revenue per month in 2025
- Event count trends
- Attendance patterns
- Sell-out trends

Year-Over-Year Comparison

GET /analytics/trends?period=YEARLY

Shows:
- Revenue by year
- Growth trends
- Performance evolution

Best Practices

For Organizers

✅ Check collection summary regularly
✅ Monitor escrow balance (upcoming payouts)
✅ Track attendance rates to improve future events
✅ Use trends to identify peak seasons
✅ Review individual event performance post-event

For Developers

✅ Cache collection summary (refresh hourly)
✅ Paginate event lists (default 20 items)
✅ Display financial amounts clearly (currency formatting)
✅ Show percentage metrics with 1 decimal (92.4%)
✅ Provide export functionality for trends

Quick Reference

HTTP Status Codes

200 OK: Successful request
401 UNAUTHORIZED: Authentication required
403 FORBIDDEN: Not event organizer
404 NOT_FOUND: Event not found

Date Formats

Event Date: LocalDateTime (2025-12-15T09:00:00)
Query Params: ISO Date (2025-01-01)

Currency

All amounts in TZS (Tanzanian Shilling)
Format: 1500000.00 (2 decimals)

Percentage Format

Format: 92.4 (1 decimal)
Range: 0.0 - 100.0

Pagination

Zero-indexed pages (0, 1, 2...)
Default size: 20
Max size: 100 (recommended)

Conclusion

The Organizer Analytics API provides comprehensive insights with:

✅ Collection Summary: Total revenue, escrow, and top performers
✅ Event Revenue: Filterable, paginated event list
✅ Event Performance: Deep dive into individual event metrics
✅ Revenue Trends: Monthly/yearly pattern analysis
✅ Real-Time: Auto-calculated from latest bookings
✅ Organizer-Focused: Restricted to event owners only

Nexgate-Event-mng-Requrements

Nexgate Platform - Check-in System Architecture

NEXGATE EVENT MANAGEMENT PLATFORM

Event Management System - Requirements & User Flow Documentation

Events Management API

Ticket Management API

Event Checkout & Payment API

Event Booking Orders API

Event Check-In System API

Organizer Analytics API

Attendance Analytics API

Event Feedback API

Organizer Analytics API

Response Structures

CollectionSummaryResponse

EventRevenueResponse

EventPerformanceResponse

RevenueTrendResponse

Endpoints

1. Get Collection Summary

2. Get Event Revenue

3. Get Event Performance

4. Get Revenue Trends

Key Calculations

Escrow vs Released

Attendance Rate

Sell-Out Percentage

Average Ticket Price

Event Status Flow

Top Performer Logic

Use Cases

Dashboard Overview

Event List with Filters

Deep Dive on Specific Event

Monthly Revenue Analysis

Year-Over-Year Comparison

Best Practices

For Organizers

For Developers

Quick Reference

HTTP Status Codes

Date Formats

Currency

Percentage Format

Pagination

Conclusion