Revenue Analytics

Revenue Analytics provides comprehensive financial intelligence including Monthly Recurring Revenue (MRR), total revenue tracking, churn analysis, and customer lifetime value metrics for administrative reporting.

API Endpoints Overview

Method	Endpoint	Description
GET	/v1/admin/analytics/revenue/total-revenue	Total revenue analytics
GET	/v1/admin/analytics/revenue/mrr	Monthly Recurring Revenue
GET	/v1/admin/analytics/revenue/mrr-pending	Pending MRR analytics
GET	/v1/admin/analytics/revenue/mrr-added	Added MRR analytics
GET	/v1/admin/analytics/revenue/other-revenue	Other revenue analytics
GET	/v1/admin/analytics/revenue/revenue-churn	Revenue churn analytics
GET	/v1/admin/analytics/revenue/avg-revenue-account	Average revenue per account
GET	/v1/admin/analytics/revenue/avg-lifetime-revenue	Average lifetime revenue

Service Methods & Business Logic

Total Revenue Analytics

totalRevenue(startDate, endDate) - Total revenue tracking

• Retrieves total revenue from all invoice collections within date range
• Calculates revenue growth rate comparing current to previous period
• Aggregates all invoice totals for comprehensive revenue analysis
• Returns total revenue data with growth percentage
• MongoDB Collections: _store.invoices
• Key Filters: { created_at: { $gte: startDate, $lte: endDate } }

Monthly Recurring Revenue (MRR)

mrr(startDate, endDate) - MRR calculation and tracking

• Calculates MRR from active and trialing subscriptions
• Joins subscription data with latest invoice amounts
• Groups revenue by month and year for time-series analysis
• Returns MRR data with monthly breakdown and growth rate
• MongoDB Collections: _store.subscriptions, _store.invoices
• Key Filters: { status: { $in: ['active', 'trialing'] }, created_at: { $gte: startDate, $lte: endDate } }

Pending MRR Analytics

mrrPending(startDate, endDate) - Pending revenue tracking

• Tracks pending MRR from active and past_due subscriptions
• Identifies void invoices that represent pending revenue
• Calculates pending MRR growth rate with historical comparison
• Returns pending MRR data with monthly breakdown
• MongoDB Collections: _store.subscriptions, _store.invoices
• Key Filters:
  • { status: { $in: ['active', 'past_due'] }, created_at: { $gte: startDate, $lte: endDate } }
  • { 'invoice.status': 'void' }

Added MRR Analytics

mrrAdded(startDate, endDate) - New MRR tracking

• Tracks newly added MRR from invoice creation within period
• Groups by month/year for time-series MRR addition analysis
• Calculates growth rate for new MRR acquisition
• Returns added MRR data with monthly breakdown and growth rate
• MongoDB Collections: _store.invoices
• Key Filters: { created_at: { $gte: startDate, $lte: endDate } }

Other Revenue Analytics

otherRevenue(startDate, endDate) - One-time payment tracking

• Tracks revenue from one-time payments and non-recurring charges
• Filters subscriptions with one_time price types
• Calculates other revenue growth rate comparing periods
• Returns other revenue data with time-series breakdown
• MongoDB Collections: _store.subscriptions, _store.prices, _store.invoices
• Key Filters:
  • { status: 'active', created_at: { $gte: startDate, $lte: endDate } }
  • { 'prices.type': 'one_time' }

Revenue Churn Analytics

revenueChurn(startDate, endDate) - Revenue loss tracking

• Tracks revenue lost from canceled subscriptions
• Calculates revenue churn based on canceled subscription invoice amounts
• Groups churn data by month/year for trend analysis
• Returns revenue churn data with growth rate analysis
• MongoDB Collections: _store.subscriptions, _store.invoices
• Key Filters: { status: 'canceled', updated_at: { $gte: startDate, $lte: endDate } }

Average Revenue Per Account

avgRevenueAccount(startDate, endDate) - ARPA calculation

• Calculates average revenue per active paying account
• Joins account data with active subscription revenue
• Computes ARPA with growth rate analysis
• Returns average revenue per account metrics
• MongoDB Collections: _accounts, _store.subscriptions, _store.invoices
• Calculation: Total MRR / Active Paying Accounts

Average Lifetime Revenue

avgLifetimeRevenue(startDate, endDate) - Customer lifetime value

• Calculates average lifetime revenue per customer
• Analyzes total revenue contribution over customer lifecycle
• Returns lifetime value metrics for business intelligence
• MongoDB Collections: _accounts, _store.subscriptions, _store.invoices
• Calculation: Total Customer Revenue / Customer Lifetime

Technical Implementation Details

MRR Calculation Pipeline

const mrrAggregation = [
  {
    $match: {
      status: { $in: ['active', 'trialing'] },
      created_at: { $gte: startDate, $lte: endDate },
    },
  },
  {
    $lookup: {
      from: '_store.invoices',
      let: { latest_invoice: '$latest_invoice' },
      pipeline: [
        {
          $match: { $expr: { $eq: ['$stripe_id', '$$latest_invoice'] } },
        },
        { $project: { total: 1 } },
      ],
      as: 'invoice',
    },
  },
  { $unwind: '$invoice' },
  {
    $group: {
      _id: {
        month: { $month: '$created_at' },
        year: { $year: '$created_at' },
      },
      count: { $sum: '$invoice.total' },
    },
  },
];

Revenue Churn Calculation

const revenueChurnRate = {
  $trunc: [
    {
      $multiply: [
        {
          $cond: [
            { $eq: [{ $first: '$previousRevenueChurnCount.total' }, 0] },
            0,
            {
              $divide: [
                {
                  $subtract: [
                    { $first: '$currentRevenueChurnData.total' },
                    { $first: '$previousRevenueChurnCount.total' },
                  ],
                },
                { $first: '$previousRevenueChurnCount.total' },
              ],
            },
          ],
        },
        100,
      ],
    },
    2,
  ],
};

Growth Rate Formula

// Standard growth rate with zero-division protection
const growthRateFormula = {
  $trunc: [
    {
      $multiply: [
        {
          $cond: [
            { $eq: [previousValue, 0] },
            0,
            { $divide: [{ $subtract: [currentValue, previousValue] }, previousValue] },
          ],
        },
        100,
      ],
    },
    2,
  ],
};

API Response Formats

Standard Revenue Response

{
  "success": true,
  "message": "SUCCESS",
  "data": {
    "currentData": {
      "total": 125000,
      "data": [
        {
          "month": 9,
          "year": 2024,
          "count": 45000
        },
        {
          "month": 10,
          "year": 2024,
          "count": 52000
        }
      ]
    },
    "growthRate": 12.5
  }
}

MRR Analytics Response

{
  "success": true,
  "message": "SUCCESS",
  "data": {
    "currentData": {
      "total": 85000,
      "data": [
        {
          "month": 9,
          "year": 2024,
          "count": 40000
        },
        {
          "month": 10,
          "year": 2024,
          "count": 45000
        }
      ]
    },
    "growthRate": 15.75
  }
}

Lifetime Revenue Response

{
  "success": true,
  "message": "SUCCESS",
  "data": {
    "currentData": {
      "lifetimeValue": 2500.0
    }
  }
}

Business Logic Workflows

MRR Calculation Flow

graph TD
    A[MRR Request] --> B[Filter Active/Trialing Subscriptions]
    B --> C[Join with Latest Invoices]
    C --> D[Group by Month/Year]
    D --> E[Sum Invoice Totals]
    E --> F[Calculate Growth Rate]
    F --> G[Format MRR Response]

    subgraph "Data Sources"
        H[Subscriptions Collection]
        I[Invoices Collection]
    end

    B --> H
    C --> I

Revenue Churn Analysis Flow

graph TD
    A[Churn Request] --> B[Filter Canceled Subscriptions]
    B --> C[Join with Invoice Data]
    C --> D[Calculate Lost Revenue]
    D --> E[Compare with Previous Period]
    E --> F[Calculate Churn Rate]
    F --> G[Return Churn Analytics]

    subgraph "Churn Metrics"
        H[Revenue Lost]
        I[Churn Rate %]
        J[Growth Rate]
    end

    F --> H --> G
    F --> I --> G
    F --> J --> G

Query Parameters

Standard Parameters

• start_date (ISO string, optional) - Revenue period start date
• end_date (ISO string, optional) - Revenue period end date

Default Behavior

• Defaults to last 30 days if no dates specified
• All revenue amounts returned in cents (Stripe format)
• Monthly grouping for time-series data where applicable

Revenue Metrics Definitions

Key Revenue Metrics

• MRR: Sum of all recurring subscription revenue normalized to monthly amounts
• Revenue Churn: Revenue lost from canceled subscriptions in period
• ARPA: Average Revenue Per Account (MRR / Active Accounts)
• LTV: Customer Lifetime Value (total revenue over customer lifetime)

Calculation Standards

• All revenue in cents to maintain precision
• Growth rates as percentages with 2 decimal places
• Monthly normalization for recurring revenue calculations
• Previous period comparison for growth analysis

Authorization & Access Control

Administrative Access

• DashClicks staff authentication required
• adminAppCheck('analytics') middleware protection
• Rate limiting with validateLimit middleware
• Comprehensive audit logging

Data Security

• Financial data access restricted to authorized personnel
• Secure handling of sensitive revenue information
• Input validation and sanitization
• Error response sanitization

Performance Optimization

Database Indexing

• Indexes on created_at and updated_at fields
• Composite indexes for subscription status and dates
• Invoice collection indexing for efficient joins

Aggregation Optimization

• Pipeline optimization for large datasets
• Memory-efficient aggregation stages
• Result caching for frequently accessed metrics

Usage Examples

Get MRR Analytics

GET /v1/admin/analytics/revenue/mrr?start_date=2024-09-01&end_date=2024-09-30
Authorization: Bearer {admin_token}

Get Revenue Churn

GET /v1/admin/analytics/revenue/revenue-churn?start_date=2024-09-01&end_date=2024-09-30
Authorization: Bearer {admin_token}

Get Average Revenue Per Account

GET /v1/admin/analytics/revenue/avg-revenue-account
Authorization: Bearer {admin_token}