# Data Overview

ChartMogul exposes subscription analytics data across six entities: individual customer records, subscription activity events, and customer count aggregations at four time granularities. Together, these give you everything you need to track revenue growth, churn patterns, and customer lifecycle changes.

## Entities

| Entity                    | Best used for                                              |
| ------------------------- | ---------------------------------------------------------- |
| Customers                 | CRM-style analysis, segmentation, cohort building          |
| Activities                | Event-level revenue tracking, churn and expansion analysis |
| Customer daily counts     | High-resolution growth tracking                            |
| Customer weekly counts    | Weekly business reviews                                    |
| Customer monthly counts   | MRR reporting, board decks                                 |
| Customer quarterly counts | QBRs, investor reporting                                   |

## Customers

#### Key fields

| Field                   | Description                                         |
| ----------------------- | --------------------------------------------------- |
| `uuid`                  | Unique ChartMogul customer identifier               |
| `external_id`           | ID from the connected billing system (e.g., Stripe) |
| `name`                  | Customer name                                       |
| `email`                 | Customer email address                              |
| `status`                | Subscription status: Active, Past Due, Cancelled    |
| `customer-since`        | Date the customer first subscribed                  |
| `mrr`                   | Current MRR contribution (in cents)                 |
| `arr`                   | Annualized revenue (in cents)                       |
| `ltv`                   | Lifetime value (in cents)                           |
| `plan`                  | Name of the current subscription plan               |
| `country`               | Customer country                                    |
| `city`                  | Customer city                                       |
| `lead_created_at`       | When the lead was first created in ChartMogul       |
| `free_trial_started_at` | Trial start date, if applicable                     |

## Activities

#### Key fields

| Field           | Description                                                          |
| --------------- | -------------------------------------------------------------------- |
| `uuid`          | Unique activity identifier                                           |
| `customer_uuid` | Links the activity to a customer record                              |
| `type`          | Activity type: new\_biz, expansion, contraction, churn, reactivation |
| `date`          | Date the activity occurred                                           |
| `mrr`           | MRR value associated with the activity (in cents)                    |
| `mrr-movement`  | Change in MRR caused by this activity                                |
| `currency`      | Currency code                                                        |
| `plan`          | Plan associated with the activity                                    |
| `description`   | Human-readable description of the event                              |

## Customer count cadences

All four count entities (daily, weekly, monthly, quarterly) share the same structure:

#### Key fields

| Field       | Description                               |
| ----------- | ----------------------------------------- |
| `date`      | Period start date                         |
| `customers` | Number of active customers in that period |

The only difference is the time granularity. Use daily counts for operational monitoring, monthly or quarterly counts for reporting and trend analysis.

## Common metric combinations

* **Activities + Customers (Join on `customer_uuid`)** — Enrich each activity event with customer metadata like plan, country, or LTV for deeper segmentation
* **Customer monthly counts over time** — Plot as a time series to visualize net customer growth trends
* **Activities filtered by `type = churn`** — Isolate churn events to calculate churn rate or identify at-risk segments
* **MRR from Customers + MRR movement from Activities** — Cross-reference current MRR with historical movements to reconcile revenue changes

## Use cases by role

{% tabs %}
{% tab title="Finance" %}

* Export monthly customer counts to Google Sheets or Excel for board-ready MRR and growth reports
* Use Activities data to reconcile MRR movements (new, expansion, churn) with billing system records
* Send ChartMogul data to BigQuery and combine with invoicing data for full revenue recognition workflows
* Use Aggregate transformations to sum MRR by plan or country for revenue mix analysis
  {% endtab %}

{% tab title="Growth & Marketing" %}

* Analyze which plans or geographies are growing fastest using Customers data segmented by `plan` and `country`
* Track trial-to-paid conversion by comparing `free_trial_started_at` with `customer-since` dates
* Feed customer count trends into ChatGPT or Claude to generate automated growth commentary for weekly updates
  {% endtab %}

{% tab title="Product & Leadership" %}

* Build weekly or quarterly dashboards in Looker Studio using customer count cadences
* Monitor expansion and contraction activities to understand upsell and downsell patterns
* Use Gemini or Perplexity with ChartMogul activity data to identify retention risks and generate executive summaries
  {% endtab %}
  {% endtabs %}

## Platform-specific notes

* MRR and LTV values are returned in **cents** — divide by 100 for display in reports
* The `start_date` parameter applies to all entities; set it far enough back to capture the history you need
* ChartMogul aggregates data from connected billing sources (Stripe, Recurly, etc.) — discrepancies usually trace back to the source system, not ChartMogul
* The `external_id` field is useful for joining ChartMogul customer records with records in your CRM or billing platform