> ## 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.

# Revenue Tracking

> Monitor membership revenue, forecasts, and financial analytics

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

<CardGroup cols={2}>
  <Card title="Total Revenue">
    Current period revenue with comparison to previous period
  </Card>

  <Card title="MRR / ARR">
    Monthly and Annual Recurring Revenue calculations
  </Card>

  <Card title="Churn Rate">
    Member cancellation rate and revenue impact
  </Card>

  <Card title="LTV">
    Average Lifetime Value per member
  </Card>
</CardGroup>

#### 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

<Tabs>
  <Tab title="Revenue Report">
    Detailed breakdown of all revenue sources with date range filtering.

    **Includes:**

    * Gross revenue
    * Refunds and chargebacks
    * Net revenue
    * Tax collected
  </Tab>

  <Tab title="Forecast Report">
    Projected revenue based on:

    * Current subscriptions
    * Historical renewal rates
    * Seasonal patterns
    * Growth trends
  </Tab>

  <Tab title="Unearned Revenue">
    For annual memberships, track:

    * Total unearned amount
    * Monthly recognition schedule
    * Current vs next financial year split
  </Tab>
</Tabs>

#### 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`](/entities/integration/payment-transaction)
* Unearned revenue tracking: [`Unearned Revenue`](/entities/integration/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

```typescript theme={null}
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"         |