canonical: https://jentic.com/apis/chartmogul.com/chartmogul

# ChartMogul API

Jentic publishes the only available OpenAPI specification for ChartMogul API, keeping it validated and agent-ready. ChartMogul ingests subscription billing data and exposes the canonical SaaS metrics - MRR, ARR, ARPA, ASP, customer churn, MRR churn, LTV, and customer count. This main surface adds write operations for customers, contacts, plans, and invoices alongside the metric reads, making it suitable for both reporting and bidirectional billing-data sync. It uses HTTP basic authentication with the API key as the username.

## For AI agents

Read SaaS metrics and write customers, plans, and invoices to ChartMogul. Basic-auth REST API with 24 endpoints covering full subscription-analytics ingestion and reporting.

## Scope

Does not handle payment processing, dunning, or invoice generation for end customers - use for importing subscription data into ChartMogul and reading SaaS metrics only.

## Capabilities

- Create, update, list, search, and delete customer records via /customers and /customers/{customerUuid}
- Maintain customer contacts via the /customers/{customerUuid}/contacts endpoints
- Register and list billing data sources with POST /data_sources and GET /data_sources
- Import plans and invoices into ChartMogul via POST /plans and POST /invoices
- Retrieve MRR, ARR, ARPA, ASP, customer count, customer churn rate, MRR churn rate, and LTV from /metrics/*
- List subscriptions for a given customer via GET /customers/{customerUuid}/subscriptions
- Trigger an activities export with POST /activities-export for downstream analysis

## Use cases

### Push subscription data from a custom billing system

Custom in-house billing systems can post customers, plans, and invoices into ChartMogul so that ChartMogul takes over MRR/ARR/churn calculation. Use POST /data_sources to register the system, then POST /customers, POST /plans, and POST /invoices to load the data. From there, the metric endpoints return the same numbers the ChartMogul UI shows.

Example prompt: Create a data source called 'Internal Billing', then create a customer with email user@example.com, create a $99/month plan, and import an invoice for that customer; verify by reading the customer back

### Build a daily SaaS metrics digest

Pull MRR, ARR, ARPA, ASP, customer count, customer churn rate, MRR churn rate, and LTV from /metrics/* endpoints once per day and post a digest into a Slack channel. Because all eight metrics share the same query-parameter shape, an agent can fetch them in a tight loop and emit a consistent table without per-metric special-casing.

Example prompt: Call /metrics/mrr, /metrics/arr, /metrics/arpa, /metrics/asp, /metrics/customer-count, /metrics/customer-churn-rate, /metrics/mrr-churn-rate, and /metrics/ltv for yesterday and emit a one-line digest

### Reconcile customer records between billing and CRM

Use GET /customers/search to look up a ChartMogul customer by external_id or email, then add or update contacts via /customers/{customerUuid}/contacts. This keeps the contact roster in ChartMogul aligned with the CRM source of truth, which matters when running churn-risk reports tied to specific stakeholders.

Example prompt: Search ChartMogul for a customer with external_id 'acme-1234', then create a contact with email cfo@acme.com and role 'CFO' on that customer

### Answer SaaS-metric questions inside an AI agent

An AI agent uses Jentic to discover ChartMogul's metric endpoints and customer endpoints, loads their schemas, and answers natural-language questions like 'what is current MRR?' or 'how many customers churned last month?' without bespoke code. Jentic's vault holds the basic-auth credential so the agent never sees the raw API key.

Example prompt: Search Jentic for 'get chartmogul mrr churn', load the operation schema, retrieve MRR churn rate for the last 90 days, and report the trend

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | /customers | Create a customer |
| GET | /customers/search | Search customers by email or external_id |
| POST | /invoices | Import invoices |
| POST | /plans | Create a plan |
| GET | /metrics/mrr | Get MRR |
| GET | /metrics/mrr-churn-rate | Get MRR churn rate |
| GET | /metrics/ltv | Get LTV |
| POST | /activities-export | Create an activities export |

## Key resources

- **Account** — Retrieve account-level identity
- **Data Sources** — Register and list billing data source connections
- **Customers** — Create, read, update, delete, search, and list customers
- **Contacts** — Manage contacts attached to a customer
- **Plans and Invoices** — Import plans and invoices into ChartMogul
- **Subscriptions** — List subscriptions for a customer
- **Metrics** — Retrieve MRR, ARR, ARPA, ASP, customer count, churn rates, and LTV
- **Activities Export** — Trigger a bulk export of activity data

## Why Jentic

- **Setup:** Wiring ChartMogul by hand means handling its HTTP Basic auth with the API key, targeting the v1 host, and attaching credentials to every import and metrics call yourself. Through Jentic you install once, import ChartMogul from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** ChartMogul imports data and reads metrics through flat operation paths rather than a per-resource URL, so limit the agent to the operations it needs, such as importing invoices or reading MRR. You choose which operations it may call, so an activities export is not included unless you add it.
- **Credential handling:** Your ChartMogul API key is stored once, encrypted, by your own Jentic One instance and used to sign the Basic auth header at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'import invoices to chartmogul' or 'get chartmogul mrr', and Jentic returns the matching ChartMogul operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **ChartMogul API (chartmogul-api)** — Companion ChartMogul surface scoped to a smaller metric-focused operation set.
- **Stripe API** — Stripe is a common upstream billing source for ChartMogul.
- **Chartbrew API** — Chartbrew is a self-hosted BI tool - chart ChartMogul metrics there for fully owned dashboards.

## FAQ

### Why is there no official OpenAPI spec for ChartMogul API?

ChartMogul does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call ChartMogul API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the ChartMogul API use?

The ChartMogul API uses HTTP basic authentication. Send your API key as the username and an empty password against api.chartmogul.com/v1. Through Jentic, the key is stored in your encrypted Jentic One instance and injected at execution time so it never enters the agent's prompt.

### Can I import invoices into ChartMogul with this API?

Yes. POST /invoices imports a batch of invoices for a customer. Before that, register the data source with POST /data_sources, create the customer with POST /customers, and create the relevant plan with POST /plans so each invoice can reference real foreign keys.

### How do I look up a ChartMogul customer by external_id?

Call GET /customers/search with the data_source_uuid and external_id query parameters. It returns the matching customer record so you can chain into /customers/{customerUuid} or /customers/{customerUuid}/subscriptions for follow-up calls.

### How do I get ChartMogul MRR through Jentic?

Run pip install jentic, set JENTIC_AGENT_API_KEY, then search 'get chartmogul mrr'. Jentic returns GET /metrics/mrr with its query parameter schema. Supply start-date and end-date and execute - the agent gets the MRR series without browsing docs.

### Are there documented rate limits for the ChartMogul API?

The OpenAPI spec does not declare rate-limit headers or per-key quotas. ChartMogul's import-heavy endpoints (POST /invoices, POST /activities-export) are usually subject to soft limits - back off on 429 responses and check any RateLimit headers the live service returns.

### Can I limit what my agent is allowed to do with the ChartMogul API?

Yes. Because you self-host Jentic One, your own rules decide which ChartMogul operations and credentials the agent may use. ChartMogul exposes flat operation paths rather than per-resource URLs, so you grant only the operations the agent needs, such as GET /metrics/mrr for reading MRR or POST /invoices for importing invoices. Anything you do not grant, like POST /activities-export or POST /customers, stays off limits.