Revenue Tracking

Track and analyze membership revenue with comprehensive dashboards, forecasting, and financial reporting.

Capabilities

Action	ROLE_CLIENT_ADMIN	ROLE_CLIENT_USER
View revenue dashboard	✅	✅
Export financial reports	✅	❌
Configure forecasting	✅	❌
View individual transactions	✅	✅

Features

Revenue Dashboard

Acceptance Criteria

Frontend

• Revenue dashboard with key metrics cards
• Interactive charts (line, bar, pie) for revenue visualization
• Comparison toggle (vs previous period)
• Export to CSV/Excel/PDF
• Loading states for data fetching
• Real-time updates when new payments received

Backend / API

• ?startDate= - Report start date
• ?endDate= - Report end date
• ?groupBy= - plan, period, type, source
• ?format= - csv, excel, pdf (for exports)

Permissions

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

Business Rules

• Revenue is recorded at payment completion (not invoice creation)
• Refunds reduce the period's revenue where refund occurred
• Unearned revenue is calculated for annual plans only
• Forecast uses 12-month historical data when available
• All amounts displayed in organization's base currency

Error Handling

• Error states return clear messages and appropriate HTTP status codes.

Revenue Breakdown

View revenue segmented by:

• By Plan - Revenue per membership plan
• By Period - Monthly, quarterly, annual views
• By Type - New vs renewal vs upgrade
• By Source - Membership, events, courses, resources

Acceptance Criteria

Frontend

• UI supports the workflows described in this feature.

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.

Financial Reports

Acceptance Criteria

Frontend

• Date range selector for all reports

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.

Transaction History

View all financial transactions:

• Payment date and amount
• Member details
• Payment method
• Transaction type (new, renewal, upgrade, refund)
• Invoice reference
• Payment status

Acceptance Criteria

Frontend

• Drill-down from summary to transaction details

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)

• Payments / transactions: Payment Transaction
• Unearned revenue tracking: Unearned Revenue

Implementation Contracts

Backend (API)

GET /api/revenue/dashboard                    # Dashboard metrics
GET /api/revenue/breakdown                    # Revenue breakdown
GET /api/revenue/transactions                 # Transaction list
GET /api/revenue/forecast                     # Revenue forecast
GET /api/revenue/unearned                     # Unearned revenue report
GET /api/revenue/export                       # Export report data

Query Parameters:

Metrics Calculations

MRR = Sum of all active monthly subscription values
    + (Sum of annual subscriptions / 12)

ARR = MRR × 12

Churn Rate = (Cancelled members in period / Total members at period start) × 100

LTV = Average Revenue Per Member × Average Member Lifespan

Data Model

interface RevenueTransaction {
  id: string;
  memberId: string;
  memberName: string;
  memberEmail: string;
  amount: number;
  currency: string;
  taxAmount: number;
  netAmount: number;
  type: 'new' | 'renewal' | 'upgrade' | 'downgrade' | 'refund';
  source: 'membership' | 'event' | 'course' | 'resource' | 'job_posting';
  paymentMethod: string;
  status: 'completed' | 'pending' | 'failed' | 'refunded';
  invoiceNumber: string;
  transactionDate: string;
}

interface RevenueDashboard {
  totalRevenue: number;
  previousPeriodRevenue: number;
  percentageChange: number;
  mrr: number;
  arr: number;
  churnRate: number;
  averageLTV: number;
  transactionCount: number;
  newMemberRevenue: number;
  renewalRevenue: number;
}

Error Handling

Error	HTTP Status	Message
Invalid date range	400	"End date must be after start date"
Date range too large	400	"Maximum date range is 2 years"
Export failed	500	"Failed to generate export"