ACM Analytics

The ACM Analytics submodule provides subscription analytics, revenue tracking, and administrative filtering for Account Client Management operations.

API Endpoints Overview

Method	Endpoint	Description
GET	/v1/admin/acm/analytics	Get subscription analytics and metrics
GET	/v1/admin/acm/filters	Get available filtering options

Service Methods & Business Logic

Subscription Analytics

queryAnalytics(filters, startDate, endDate, types, ...) - Comprehensive subscription analytics

• Service Method: acmService.queryAnalytics()
• Controller: acmController.getAnalytics
• Route: GET /v1/admin/acm/analytics
• Parameters:
  • start_date, end_date - Date range for analytics
  • types - Analytics types: MRR, ASL, RET, EXP, NEW, CAN, CHR, RATE, CANBD
  • products - Product filtering (defaults to allowed departments)
  • specialist, team_lead, manager - Team member filtering
  • project_status - Project status filtering
  • unassigned - Filter for unassigned subscriptions
  • trialing - Filter for trialing subscriptions
• Analytics Types:
  • MRR: Monthly Recurring Revenue with pricing adjustments
  • ASL: Average Subscription Lifecycle metrics
  • RET: Retention analytics and trends
  • EXP: Expansion revenue tracking
  • NEW: New subscription analytics
  • CAN: Cancellation analytics and feedback
  • CHR: Churn rate calculations
  • RATE: Conversion and retention rates
  • CANBD: Cancellation breakdown analysis
• Returns: Analytics data with comparison periods and trend analysis

Filter Management

queryFilters({ filters, accId }) - Available filtering options for ACM operations

• Service Method: acmService.queryFilters()
• Controller: acmController.getFilters
• Route: GET /v1/admin/acm/filters
• Parameters:
  • accId - Account ID for filtering context
• Process Flow:
  1. User Role Filtering: Filters users by allowed ACM roles
  2. Department Filtering: Gets subscription counts by product type
  3. User Assignment Counts: Counts subscriptions by assigned users
  4. Project Status Counts: Subscription counts by project status
  5. Unassigned/Trialing Counts: Special category counts
• MongoDB Collections: _users, stripe.subscriptions
• Returns: Filter options with counts for dashboard dropdowns and controls

Technical Implementation Details

Analytics Processing Pipeline

The analytics system processes multiple subscription metrics simultaneously using Promise.allSettled for parallel execution:

const queryAnalytics = async ({
  filters,
  startDate,
  endDate,
  types,
  products,
  specialist,
  team_lead,
  manager,
  unassigned,
  trialing,
}) => {
  // Date range processing with automatic period comparison
  let numberOfDays = endDate.diff(startDate, 'days') + 1;
  let prevStartDate = moment(startDate).subtract(numberOfDays, 'days');

  // Parallel analytics execution for multiple types
  let promises = [];
  for (const type of types) {
    switch (type) {
      case 'MRR':
        promises.push(fetchMRR(params));
        break;
      case 'ASL':
        promises.push(fetchASL(params));
        break;
      case 'RET':
        promises.push(fetchRET(params));
        break;
      // ... other analytics types
    }
  }

  const responses = await Promise.allSettled(promises);
  return transformData(responses);
};

Price Adjustment Calculations

The system includes sophisticated price adjustment logic for different billing intervals:

const adjustPrice = () => ({
  adjustedPrice: {
    $divide: [
      {
        $ifNull: [
          {
            $switch: {
              branches: [
                {
                  case: { $eq: ['$items.data.price.recurring.interval', 'day'] },
                  then: {
                    $multiply: ['$items.data.price.unit_amount', '$items.data.quantity', 30],
                  },
                },
                {
                  case: { $eq: ['$items.data.price.recurring.interval', 'week'] },
                  then: { $multiply: ['$items.data.price.unit_amount', '$items.data.quantity', 4] },
                },
                // ... monthly, yearly calculations
              ],
              default: 0,
            },
          },
          0,
        ],
      },
      100,
    ],
  },
});

Filter Aggregation Pipeline

The filter system uses MongoDB aggregation to provide dynamic filtering options:

const queryFilters = async ({ filters, accId }) => {
  // User aggregation for team member filtering
  const userQuery = [
    {
      $match: {
        account: new ObjectId(accId),
        'dashclicks.acm.role': { $in: allowedRoles },
      },
    },
    {
      $group: {
        _id: '$dashclicks.acm.role',
        users: { $push: '$$ROOT' },
      },
    },
  ];

  // Subscription aggregation for counts and filtering
  const subQuery = [
    {
      $match: {
        'plan.metadata.product_type': { $in: allowedProducts },
        status: { $in: ['active', 'past_due', 'trialing'] },
      },
    },
    {
      $facet: {
        product_counts: [
          /* product grouping */
        ],
        user_counts: [
          /* user assignment counts */
        ],
        project_status_counts: [
          /* status grouping */
        ],
        unassigned: [
          /* unassigned count */
        ],
        trialing: [
          /* trialing count */
        ],
      },
    },
  ];
};

API Response Formats

Analytics Response

{
  "success": true,
  "message": "SUCCESS",
  "data": {
    "MRR": {
      "comparison_data": [
        {
          "curr": {
            "total_amt": 15420.5,
            "count": 145,
            "date": "2024-10-15T00:00:00.000Z",
            "from": "2024-09-15T00:00:00.000Z",
            "to": "2024-10-15T00:00:00.000Z"
          },
          "prev": {
            "total_amt": 14200.3,
            "count": 132,
            "date": "2024-09-15T00:00:00.000Z",
            "from": "2024-08-15T00:00:00.000Z",
            "to": "2024-09-15T00:00:00.000Z"
          }
        }
      ],
      "currTotal": { "total_amt": 15420.5, "count": 145 },
      "prevTotal": { "total_amt": 14200.3, "count": 132 }
    }
  }
}

Filters Response

{
  "success": true,
  "message": "SUCCESS",
  "data": {
    "filters": {
      "departments": [
        { "value": "seo", "label": "SEO", "enabled": true },
        { "value": "ppc", "label": "PPC", "enabled": true }
      ],
      "roles": [
        { "value": "specialist", "label": "Specialist", "enabled": true },
        { "value": "team_lead", "label": "Team Lead", "enabled": true }
      ]
    },
    "users": [
      {
        "role": "specialist",
        "users": [{ "_id": "user123", "name": "John Doe", "image": "profile.jpg" }]
      }
    ],
    "project_status_counts": {
      "active": 45,
      "completed": 23,
      "paused": 8
    },
    "unassigned": 12,
    "trialing": 7
  }
}

Query Parameters

Analytics Parameters

• start_date (string) - Start date for analytics period (ISO 8601)
• end_date (string) - End date for analytics period (ISO 8601)
• types (array) - Analytics types: ['MRR', 'ASL', 'RET', 'EXP', 'NEW', 'CAN', 'CHR', 'RATE', 'CANBD']
• products (array) - Product filtering (defaults to user's allowed departments)
• specialist (array) - Filter by specialist user IDs
• team_lead (array) - Filter by team lead user IDs
• manager (array) - Filter by manager user IDs
• project_status (string) - Filter by project status
• unassigned (boolean) - Include only unassigned subscriptions
• trialing (boolean) - Include only trialing subscriptions

Filter Parameters

• No parameters required - returns all available filter options for the account

Error Handling

Analytics Error Scenarios

• 400 Bad Request: Invalid date range or analytics type parameters
• 403 Forbidden: Insufficient ACM permissions or role access
• 500 Internal Server Error: Analytics aggregation failures or database issues

Usage Examples

Get Subscription Analytics

GET /v1/admin/acm/analytics?start_date=2024-01-01&end_date=2024-12-31&types=MRR,NEW,CAN&products=seo,ppc&specialist=user123
Authorization: Bearer {admin_token}

Get Available Filters

GET /v1/admin/acm/filters
Authorization: Bearer {admin_token}

Get MRR Analytics with Team Filtering

GET /v1/admin/acm/analytics?start_date=2024-10-01&end_date=2024-10-31&types=MRR&team_lead=user456&unassigned=false
Authorization: Bearer {admin_token}

Key Analytics Types

Revenue Analytics

• MRR (Monthly Recurring Revenue): Normalized monthly revenue with interval adjustments
• ASL (Average Subscription Lifecycle): Subscription duration and lifecycle metrics
• EXP (Expansion): Revenue expansion from existing subscriptions

Performance Analytics

• RET (Retention): Subscription retention rates and trends
• CAN (Cancellations): Cancellation analytics with feedback data
• CHR (Churn Rate): Customer churn rate calculations
• NEW (New Subscriptions): New subscription acquisition metrics

Advanced Analytics

• RATE: Conversion and retention rate calculations
• CANBD (Cancellation Breakdown): Detailed cancellation analysis

Important Notes

• Analytics support automatic period-over-period comparison
• Date ranges automatically calculate previous period comparisons
• Price adjustments normalize different billing intervals to monthly equivalents
• Role-based filtering ensures users only see data they have permission to access
• All analytics require proper DashClicks staff authentication
• Complex aggregation pipelines optimize performance for large datasets