> For the complete documentation index, see [llms.txt](https://docs.coupler.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.coupler.io/sources/category/finance-and-accounting/chartmogul.md).

# Chartmogul

Connect ChartMogul to Coupler.io to sync MRR, churn, LTV, and customer data into Google Sheets or data warehouses.

ChartMogul is a subscription analytics platform that helps SaaS and subscription businesses track revenue metrics like MRR, churn, LTV, and customer growth. It pulls billing data from payment processors and subscription platforms into a single analytics layer. Connecting ChartMogul to Coupler.io lets you export that data into spreadsheets, data warehouses, or AI tools without manual exports.

**Why connect ChartMogul to Coupler.io?**

* Sync customer records, subscription activities, and growth counts to Google Sheets, Excel, BigQuery, or Looker Studio
* Send ChartMogul metrics to AI destinations like ChatGPT, Claude, or Gemini for automated analysis and commentary
* Combine customer counts with activity data using Append or Join transformations to build richer revenue dashboards
* Schedule recurring syncs so your reports always reflect the latest subscription data

## Prerequisites

* A ChartMogul account with at least one connected data source
* A ChartMogul API key (available from your account settings)
* A Coupler.io account

## Quick start

{% hint style="success" %}
If you want a high-level revenue snapshot, start with the **Customer monthly counts** entity — it gives you a clean time series of customer growth without the noise of individual records.
{% endhint %}

## How to connect

{% stepper %}
{% step %}
**Create a new data flow in Coupler.io.** From your Coupler.io dashboard, click **Add data flow**, then search for and select **ChartMogul** as the source.
{% endstep %}

{% step %}
**Enter your ChartMogul API key.** In ChartMogul, go to **Profile → API Keys** and copy your secret key. Paste it into the API key field in Coupler.io.
{% endstep %}

{% step %}
**Select an entity.** Choose what data you want to export — Customers, Activities, or one of the customer count cadences (daily, weekly, monthly, quarterly).
{% endstep %}

{% step %}
**Set a start date.** Use the date picker to choose how far back to pull historical data. This filters the data returned for the selected entity.
{% endstep %}

{% step %}
**Choose a destination and run the data flow.** Select your destination — Google Sheets, Excel, BigQuery, Looker Studio, or an AI tool like ChatGPT or Claude — then click **Run** to execute your first manual sync.
{% endstep %}
{% endstepper %}

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

## ChartMogul common issues

### Connection issues

<details>

<summary>Authentication failed / invalid API key</summary>

Double-check that you copied the full API key from ChartMogul without any trailing spaces. In ChartMogul, go to **Profile → API Keys** and regenerate the key if needed, then paste the new value into Coupler.io. Note that ChartMogul has both a secret key and an account token — Coupler.io requires the **secret key**.

</details>

<details>

<summary>Data flow fails on first run with no clear error</summary>

This can happen if your ChartMogul account has no data for the selected start date range. Try moving the start date forward to a period you know has subscription activity, then re-run the data flow.

</details>

### Missing data

<details>

<summary>Customer or activity records are missing</summary>

ChartMogul only exposes data from connected billing integrations. If a customer or activity exists in your payment processor but not in ChartMogul, the source integration may not be configured correctly. Check your ChartMogul data sources under **Settings → Integrations**.

</details>

<details>

<summary>No data returned for the selected date range</summary>

If the entity returns empty results, your start date may be set too recently. Use the date picker to move it earlier. Also confirm the entity has data in ChartMogul's own UI for that period before troubleshooting Coupler.io.

</details>

<details>

<summary>Customer count entities return fewer rows than expected</summary>

Customer count cadences (daily, weekly, monthly, quarterly) only include periods where ChartMogul has computed a count. If your account is new or the billing integration was connected recently, historical counts may not be backfilled. ChartMogul calculates these counts from the date the integration was first connected.

</details>

### Permission errors

<details>

<summary>API key works in ChartMogul but returns a 403 in Coupler.io</summary>

Some ChartMogul plans restrict API access or limit the endpoints available. Confirm that your plan includes API access and that the key has not been scoped to read-only in a way that blocks the endpoints Coupler.io uses. If you're on a trial plan, API access may be limited.

</details>

### Data discrepancies

<details>

<summary>MRR figures in Coupler.io don't match what I see in ChartMogul's dashboard</summary>

ChartMogul returns MRR values in **cents**, not dollars (or your local currency). Divide the exported `mrr` and `arr` values by 100 to match the figures shown in the ChartMogul UI. If the discrepancy persists after converting, check whether the ChartMogul dashboard applies additional filters (e.g., by plan or segment) that aren't reflected in the raw export.

</details>

<details>

<summary>Activity counts differ from ChartMogul reports</summary>

ChartMogul's built-in reports sometimes de-duplicate or roll up certain activity types. The raw Activities entity in Coupler.io reflects individual events without that processing. If you need aggregated figures, use Coupler.io's Aggregate transformation to group and sum by activity type.

</details>

### Rate limits

<details>

<summary>Data flow is slow or times out on large datasets</summary>

ChartMogul enforces API rate limits that vary by plan. If you're pulling a large date range of Activities or a high-volume Customers list, the sync may take longer than expected. Narrow your start date to reduce the data volume, or split large pulls into separate data flows by entity.

</details>

## ChartMogul FAQ

<details>

<summary>Where do I find my ChartMogul API key?</summary>

Log into ChartMogul and go to **Profile → API Keys**. Your secret key is listed there. If you haven't generated one yet, click **Create API Key**. Copy the secret key (not the account token) and paste it into Coupler.io when setting up the data flow.

</details>

<details>

<summary>Which entity should I use for MRR reporting?</summary>

For trend reporting, **Customer monthly counts** gives you a clean time series of active customer numbers, but it doesn't include MRR directly. For MRR values, use the **Customers** entity — each record includes the customer's current `mrr` contribution. To see MRR movements over time (new, expansion, churn), use the **Activities** entity filtered by event type.

</details>

<details>

<summary>Can I combine data from multiple ChartMogul accounts?</summary>

Yes. Create a separate source connection in Coupler.io for each ChartMogul account, then use the **Append** transformation to merge the data into a single output. This is useful if you run multiple products or brands under separate ChartMogul workspaces.

</details>

<details>

<summary>Why do my customer counts not go back to our company's founding date?</summary>

ChartMogul calculates customer counts from the date your billing integration was first connected, not from your company's founding date. Historical data before the integration was set up may not be available unless you performed a historical data import in ChartMogul.

</details>

<details>

<summary>Can I send ChartMogul data to an AI tool for analysis?</summary>

Yes. Coupler.io supports AI destinations including ChatGPT, Claude, Gemini, Perplexity, Cursor, and OpenClaw. You can pipe your Activities or customer count data directly into these tools to generate automated insights, churn commentary, or revenue summaries on a scheduled basis.

</details>

<details>

<summary>How do I track churn specifically?</summary>

Use the **Activities** entity and filter by `type = churn`. Each churn event includes the customer UUID, the date, and the MRR lost. You can Join this with the Customers entity on `customer_uuid` to add plan, country, or LTV context to each churn event.

</details>

<details>

<summary>What's the difference between the four customer count cadences?</summary>

All four entities (daily, weekly, monthly, quarterly) return the same two fields — a date and a customer count — but at different time granularities. Use daily for operational monitoring, weekly for team standups, monthly for MRR reports, and quarterly for investor or board presentations.

</details>

{% hint style="info" %}
For a full breakdown of available fields and metric combinations, see the [Data Overview](#chartmogul-data-overview) article. For sync errors and missing data, check [Common Issues](#chartmogul-common-issues).
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.coupler.io/sources/category/finance-and-accounting/chartmogul.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
