> 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/best-practices.md).

# Best Practices

## Recommended setup

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th></tr></thead><tbody><tr><td><strong>Use monthly counts for dashboards, activities for analysis</strong></td><td>Customer monthly counts are pre-aggregated and load fast — ideal for KPI dashboards. Use the Activities entity when you need event-level detail for churn analysis or cohort work.</td></tr><tr><td><strong>Join Activities with Customers for richer segmentation</strong></td><td>The Activities entity alone doesn't include plan, country, or LTV. Use Coupler.io's Join transformation on <code>customer_uuid</code> to enrich events with customer metadata before building reports.</td></tr><tr><td><strong>Convert cents to currency in your destination</strong></td><td>MRR, ARR, and LTV fields are in cents. Add a calculated column in Google Sheets or a transformation in BigQuery to divide by 100 — do this once at the destination level rather than correcting it repeatedly.</td></tr><tr><td><strong>Set your start date to match your billing history</strong></td><td>ChartMogul can return data from the day your first subscription was recorded. Set the start date to your earliest billing date to capture full historical trends, especially for LTV and cohort analysis.</td></tr></tbody></table>

## Data refresh and scheduling

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th></tr></thead><tbody><tr><td><strong>Daily counts need daily syncs</strong></td><td>If you're using the Customer daily count entity for operational monitoring, schedule your data flow to run daily so each day's count is captured. Daily counts aren't backfilled retroactively if you miss a run.</td></tr><tr><td><strong>Monthly and quarterly entities don't need frequent refreshes</strong></td><td>For board or investor reports using monthly or quarterly counts, a weekly or even monthly sync is sufficient. Over-syncing these entities wastes API calls without adding value.</td></tr></tbody></table>

## Performance optimization

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th></tr></thead><tbody><tr><td><strong>Narrow the date range for Activities</strong></td><td>The Activities entity can grow large quickly for high-volume businesses. If you only need recent events, set the start date to the last 90 or 180 days rather than pulling all-time history every sync.</td></tr><tr><td><strong>Use separate data flows per entity</strong></td><td>Splitting Customers and Activities into separate data flows makes it easier to debug sync issues and control refresh frequency independently for each entity.</td></tr></tbody></table>

## Common pitfalls

{% hint style="danger" %}
Don't build revenue reports directly from raw MRR fields without converting from cents. A customer showing $1,200 MRR in ChartMogul will appear as 120000 in the raw export — always divide by 100 before displaying or aggregating these values.
{% endhint %}

{% columns %}
{% column %}
**Do**

* Use the `external_id` field to join ChartMogul customers with your CRM or Stripe records
* Filter Activities by `type` to isolate specific events like churn or expansion before aggregating
* Use Append to combine customer count data from multiple ChartMogul accounts if you run multiple products
  {% endcolumn %}

{% column %}
**Don't**

* Pull all-time Activities history on every scheduled sync — use an incremental start date instead
* Mix customer count cadences (e.g., daily and monthly) in the same chart without normalizing the time axis
* Assume ChartMogul counts include trial users — counts reflect paying subscribers unless your integration is configured otherwise
  {% endcolumn %}
  {% endcolumns %}


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.