Subscription Analytics

Subscription Analytics provides detailed insights into subscription lifecycle management, including active subscription tracking, new subscription analysis, and subscription churn rates for business intelligence.

API Endpoints Overview

Method	Endpoint	Description
GET	/v1/admin/analytics/subscription/active-subscriptions	Active subscription analytics
GET	/v1/admin/analytics/subscription/new-subscriptions	New subscription analytics
GET	/v1/admin/analytics/subscription/subscription-churn	Subscription churn analytics

Service Methods & Business Logic

Active Subscriptions Analytics

activeSubscriptions(startDate, endDate, product) - Active subscription tracking

• Retrieves active subscription analytics with optional product filtering
• Calculates subscription growth rate comparing current to previous period
• Supports product-specific filtering for detailed analysis
• Returns active subscription data with growth metrics
• MongoDB Collections: _store.subscriptions, _store.prices, _store.products
• Key Filters:
  • { status: 'active', created_at: { $gte: startDate, $lte: endDate } }
  • Optional product filtering: { 'product.metadata.product_type': product }

New Subscriptions Analytics

newSubscriptions(startDate, endDate, product) - New subscription tracking

• Tracks new subscriptions including active and trialing status
• Supports product-specific filtering for targeted analysis
• Calculates new subscription growth rate with historical comparison
• Returns new subscription data with time-series breakdown
• MongoDB Collections: _store.subscriptions, _store.prices, _store.products
• Key Filters:
  • { status: { $in: ['active', 'trialing'] }, created_at: { $gte: startDate, $lte: endDate } }
  • Optional product filtering: { 'product.metadata.product_type': product }

Subscription Churn Analytics

subscriptionChurn(startDate, endDate, product) - Churn rate calculation

• Calculates subscription churn rate using canceled subscriptions
• Compares against active subscriptions at period beginning
• Supports product-specific churn analysis
• Churn Rate Formula: (Canceled Subscriptions / Active at Period Start) * 100
• Returns churn rate percentage with supporting metrics
• MongoDB Collections: _store.subscriptions, _store.prices, _store.products
• Key Filters:
  • { status: 'canceled', updated_at: { $gte: startDate, $lte: endDate } }
  • Optional product filtering: { 'product.metadata.product_type': product }

Technical Implementation Details

Product Filtering Pipeline

const getFilterByProduct = product => {
  return [
    {
      $lookup: {
        from: '_store.prices',
        let: { price: '$price' },
        pipeline: [
          { $match: { $expr: { $eq: ['$_id', '$$price'] } } },
          { $project: { product: 1, metadata: 1 } },
        ],
        as: 'price',
      },
    },
    { $unwind: '$price' },
    {
      $lookup: {
        from: '_store.products',
        let: { product: '$price.product' },
        pipeline: [
          { $match: { $expr: { $eq: ['$_id', '$$product'] } } },
          { $project: { metadata: 1, platform_type: 1 } },
        ],
        as: 'product',
      },
    },
    { $unwind: '$product' },
    {
      $match: product ? { 'product.metadata.product_type': product } : {},
    },
  ];
};

Subscription Churn Calculation

const subscriptionChurnAggregation = [
  {
    $facet: {
      activeSubscriptionCountAtBegining: [
        { $match: { status: 'active', updated_at: { $lte: previousEndDate } } },
        ...filterByProduct,
        { $count: 'total' },
      ],
      currentSubscriptionChurnData: [
        { $match: { status: 'canceled', updated_at: { $gte: startDate, $lte: endDate } } },
        ...filterByProduct,
        {
          $group: {
            _id: '$updated_at',
            count: { $sum: 1 },
          },
        },
      ],
    },
  },
  {
    $set: {
      churnRate: {
        $ifNull: [
          {
            $trunc: [
              {
                $multiply: [
                  {
                    $divide: [
                      { $first: '$currentSubscriptionChurnData.total' },
                      { $first: '$activeSubscriptionCountAtBegining.total' },
                    ],
                  },
                  100,
                ],
              },
              2,
            ],
          },
          0,
        ],
      },
    },
  },
];

Active Subscription Growth Tracking

const activeSubscriptionTracking = [
  {
    $match: {
      status: 'active',
      created_at: { $gte: startDate, $lte: endDate },
    },
  },
  ...getFilterByProduct(product),
  {
    $group: {
      _id: '$created_at',
      count: { $sum: 1 },
    },
  },
  {
    $project: {
      tmp: {
        date: '$_id',
        count: '$count',
      },
    },
  },
  {
    $group: {
      _id: null,
      total: { $sum: '$tmp.count' },
      data: { $addToSet: '$tmp' },
    },
  },
];

API Response Formats

Active Subscriptions Response

{
  "success": true,
  "message": "SUCCESS",
  "data": {
    "currentData": {
      "total": 850,
      "data": [
        {
          "date": "2024-10-01T00:00:00.000Z",
          "count": 25
        },
        {
          "date": "2024-10-02T00:00:00.000Z",
          "count": 32
        }
      ]
    },
    "growthRate": 18.5
  }
}

Subscription Churn Response

{
  "success": true,
  "message": "SUCCESS",
  "data": {
    "currentSubscriptionChurnData": {
      "total": 45,
      "data": [
        {
          "date": "2024-10-01T00:00:00.000Z",
          "count": 12
        },
        {
          "date": "2024-10-02T00:00:00.000Z",
          "count": 8
        }
      ]
    },
    "churnRate": 5.25,
    "activeSubscriptionCountAtBegining": 800
  }
}

New Subscriptions Response

{
  "success": true,
  "message": "SUCCESS",
  "data": {
    "currentData": {
      "total": 125,
      "data": [
        {
          "date": "2024-10-01T00:00:00.000Z",
          "count": 15
        },
        {
          "date": "2024-10-02T00:00:00.000Z",
          "count": 22
        }
      ]
    },
    "growthRate": 25.0
  }
}

Business Logic Workflows

Active Subscription Tracking Flow

graph TD
    A[Active Subscription Request] --> B[Apply Date Range Filter]
    B --> C[Apply Product Filter]
    C --> D[Query Active Subscriptions]
    D --> E[Join with Product Data]
    E --> F[Calculate Growth Rate]
    F --> G[Format Response]

    subgraph "Product Filtering"
        H[Lookup Prices]
        I[Lookup Products]
        J[Filter by Product Type]
    end

    C --> H --> I --> J --> D

Subscription Churn Analysis Flow

graph TD
    A[Churn Analysis Request] --> B[Get Active Subscriptions at Period Start]
    A --> C[Get Canceled Subscriptions in Period]

    B --> D[Calculate Churn Rate]
    C --> D

    D --> E[Churn Rate = Canceled / Active Start * 100]
    E --> F[Return Churn Analytics]

    subgraph "Supporting Data"
        G[Period Start Active Count]
        H[Canceled Count]
        I[Time Series Data]
    end

    D --> G --> F
    D --> H --> F
    D --> I --> F

Query Parameters

Standard Parameters

• start_date (ISO string, optional) - Analytics period start date
• end_date (ISO string, optional) - Analytics period end date
• product (string, optional) - Filter by specific product type

Product Filtering

Available product types for filtering:

• software - Software subscriptions
• services - Service subscriptions
• digital - Digital product subscriptions

Default Behavior

• Date range defaults to last 30 days if not specified
• No product filtering applied if product parameter omitted
• Growth rate calculated against same duration previous period

Subscription Metrics Definitions

Key Subscription Metrics

• Active Subscriptions: Total subscriptions with 'active' status
• New Subscriptions: Subscriptions created in period (active + trialing)
• Subscription Churn: Percentage of subscriptions canceled in period
• Growth Rate: Period-over-period percentage change

Churn Rate Calculation

The subscription churn rate is calculated using the standard formula:

Churn Rate = (Subscriptions Canceled in Period / Active Subscriptions at Period Start) × 100

This provides an accurate measure of subscription attrition over time.

Authorization & Access Control

Administrative Access

• DashClicks staff authentication required
• adminAppCheck('analytics') middleware protection
• Rate limiting with validateLimit middleware
• Audit logging for all subscription analytics access

Data Privacy

• Subscription data access restricted to authorized staff
• No customer PII exposed in analytics responses
• Secure handling of subscription metrics
• Input validation and sanitization

Performance Optimization

Database Optimization

• Indexes on subscription status and date fields
• Composite indexes for efficient product filtering
• Optimized aggregation pipelines for large datasets

Query Efficiency

• Product filtering applied early in pipeline
• Efficient date range queries with proper indexing
• Memory-efficient aggregation stages

Usage Examples

Get Active Subscriptions for All Products

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

Get Software Product Churn Rate

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

Get New Subscriptions Analytics

GET /v1/admin/analytics/subscription/new-subscriptions?product=services
Authorization: Bearer {admin_token}