> ## Documentation Index
> Fetch the complete documentation index at: https://memberpulseptyltd.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Event Reporting

> Analytics and reports for event performance, attendance, and revenue

Comprehensive analytics and reporting for event performance, attendance metrics, revenue tracking, and member engagement.

## Capabilities

| Action           | ROLE\_CLIENT\_ADMIN | ROLE\_CLIENT\_USER |
| ---------------- | ------------------- | ------------------ |
| View reports     | ✅                   | ✅                  |
| Export reports   | ✅                   | ❌                  |
| Schedule reports | ✅                   | ❌                  |

## Features

### Report Types

<Tabs>
  <Tab title="Event Summary">
    Overview of individual event performance:

    * Registration count vs capacity
    * Revenue generated
    * Attendance rate
    * Ticket type breakdown
    * Member vs non-member ratio
  </Tab>

  <Tab title="Attendance Report">
    Detailed attendance analytics:

    * Check-in timeline
    * Session attendance (multi-session)
    * No-show analysis
    * CPD points awarded
    * Geographic distribution
  </Tab>

  <Tab title="Revenue Report">
    Financial performance:

    * Gross revenue
    * Refunds and adjustments
    * Net revenue
    * Revenue by ticket type
    * Promo code usage
  </Tab>

  <Tab title="Trend Analysis">
    Historical patterns:

    * Event attendance over time
    * Revenue trends
    * Popular event types
    * Seasonal patterns
    * Member engagement trends
  </Tab>
</Tabs>

#### Acceptance Criteria

##### Frontend

* [ ] Report builder interface
* [ ] Scheduled report configuration
* [ ] Interactive charts (line, bar, pie)
* [ ] Date range selector
* [ ] Event filter dropdown
* [ ] Export to PDF/Excel/CSV
* [ ] Drill-down from summary to details
* [ ] Comparison views (vs previous period)

##### Backend / API

* [ ] `?startDate=` - Report start date
* [ ] `?endDate=` - Report end date
* [ ] `?eventIds=` - Filter by events
* [ ] `?eventType=` - Filter by type
* [ ] `?groupBy=` - Grouping option

##### Permissions

* [ ] Access is restricted per the Capabilities matrix on this page (or equivalent role rules).

##### Business Rules

* [ ] Reports default to current month if no date specified
* [ ] Scheduled reports run at organization's timezone midnight
* [ ] Maximum date range is 2 years
* [ ] Export includes all data points, not just visible
* [ ] Sensitive financial data requires ROLE\_CLIENT\_ADMIN role

##### Error Handling

* [ ] Error states return clear messages and appropriate HTTP status codes.

### Dashboard Metrics

<CardGroup cols={4}>
  <Card title="Total Events">
    Events held in period
  </Card>

  <Card title="Total Attendees">
    Unique attendees
  </Card>

  <Card title="Revenue">
    Total event revenue
  </Card>

  <Card title="Avg Attendance">
    Average per event
  </Card>
</CardGroup>

#### Acceptance Criteria

##### Frontend

* [ ] Report dashboard with key metrics

##### Backend / API

* [ ] Backend behavior supports this feature as documented.

##### Permissions

* [ ] Access is restricted per the Capabilities matrix on this page (or equivalent role rules).

##### Business Rules

* [ ] All business rules for this feature are enforced.

##### Error Handling

* [ ] Error states return clear messages and appropriate HTTP status codes.

#### Data Model Cross‑Reference (Entities)

Event reporting derives its metrics from these entities:

* Events and their configuration: [`Event`](/entities/core/event)
* Registrations, attendance, and ticket types purchased: [`Event Ticket`](/entities/core/event-ticket)
* Revenue (paid tickets) and refunds (when implemented): [`Payment Transaction`](/entities/integration/payment-transaction)

> Note: this page is a reporting/analytics view; the spreadsheet does not provide a dedicated reporting field inventory beyond the upstream event/ticket/attendance primitives.

### Report Builder

Create custom reports with:

* **Date Range** - Select reporting period
* **Event Filter** - Specific events or all
* **Metrics Selection** - Choose data points
* **Grouping** - By event, type, month, etc.
* **Visualization** - Charts, tables, or both

#### Acceptance Criteria

##### Frontend

* [ ] Report Builder workflow is implemented in the UI as described.

##### Backend / API

* [ ] Backend behavior supports Report Builder as documented.

##### Permissions

* [ ] Access is restricted per the Capabilities matrix on this page (or equivalent role rules).

##### Business Rules

* [ ] All business rules for this feature are enforced.

##### Error Handling

* [ ] Error states return clear messages and appropriate HTTP status codes.

### Scheduled Reports

Automate report delivery:

1. Configure report parameters
2. Set schedule (daily, weekly, monthly)
3. Select recipients
4. Choose format (PDF, Excel, CSV)
5. Reports delivered via email

#### Acceptance Criteria

##### Frontend

* [ ] Scheduled Reports workflow is implemented in the UI as described.

##### Backend / API

* [ ] Backend behavior supports Scheduled Reports as documented.

##### Permissions

* [ ] Access is restricted per the Capabilities matrix on this page (or equivalent role rules).

##### Business Rules

* [ ] All business rules for this feature are enforced.

##### Error Handling

* [ ] Error states return clear messages and appropriate HTTP status codes.

## Implementation Contracts

### Backend (API)

```
GET /api/events/reports/summary              # Overall summary
GET /api/events/{id}/reports/summary         # Single event summary
GET /api/events/reports/attendance           # Attendance report
GET /api/events/reports/revenue              # Revenue report
GET /api/events/reports/trends               # Trend analysis

POST /api/events/reports/custom              # Custom report builder
POST /api/events/reports/export              # Export report

GET  /api/events/reports/scheduled           # List scheduled reports
POST /api/events/reports/scheduled           # Create scheduled report
PUT  /api/events/reports/scheduled/{id}      # Update schedule
DELETE /api/events/reports/scheduled/{id}    # Delete schedule
```

**Query Parameters:**

### Data Model

```typescript theme={null}
interface EventReportSummary {
  period: {
    startDate: string;
    endDate: string;
  };
  
  // Overview
  totalEvents: number;
  totalRegistrations: number;
  totalAttendees: number;
  totalRevenue: number;
  
  // Averages
  avgRegistrationsPerEvent: number;
  avgAttendanceRate: number;
  avgRevenuePerEvent: number;
  
  // Breakdown
  byEventType: {
    type: string;
    count: number;
    registrations: number;
    revenue: number;
  }[];
  
  byMonth: {
    month: string;
    events: number;
    registrations: number;
    revenue: number;
  }[];
}

interface ScheduledReport {
  id: string;
  name: string;
  reportType: string;
  parameters: Record<string, any>;
  schedule: 'daily' | 'weekly' | 'monthly';
  dayOfWeek?: number;  // For weekly
  dayOfMonth?: number; // For monthly
  recipients: string[];
  format: 'pdf' | 'excel' | 'csv';
  active: boolean;
  lastRunAt?: string;
  nextRunAt: string;
}
```

### Report Metrics

| Metric               | Calculation                                  |
| -------------------- | -------------------------------------------- |
| Attendance Rate      | (Checked In / Registered) × 100              |
| No-Show Rate         | (Registered - Checked In) / Registered × 100 |
| Revenue Per Attendee | Total Revenue / Checked In                   |
| Member Ratio         | Members / Total Registered × 100             |
| Capacity Utilization | Registered / Capacity × 100                  |

### Error Handling

| Error              | HTTP Status | Message                             |
| ------------------ | ----------- | ----------------------------------- |
| Invalid date range | 400         | "End date must be after start date" |
| Range too large    | 400         | "Maximum date range is 2 years"     |
| Export failed      | 500         | "Failed to generate export"         |
| No data            | 200         | Returns empty result set            |