> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nekt.com/llms.txt
> Use this file to discover all available pages before exploring further.

# ChartMogul as a data source

> Bring customers, subscriptions, plans, invoices, MRR activities and daily SaaS metrics (MRR, ARR, churn, LTV) from ChartMogul to Nekt.

ChartMogul is a subscription analytics platform: it reads your billing systems (Stripe, Chargebee, Recurly, App Store, custom imports and others) and turns them into SaaS metrics such as MRR, ARR, churn and LTV. This connector reads your ChartMogul account through its public API and brings your customers and their subscriptions, plans and plan groups, invoices with their line items and payments, every MRR movement (new business, expansion, contraction, churn, reactivation) and your key metrics day by day.

> [!NOTE]
>
> The connector only reads data. It never creates, changes or deletes anything in ChartMogul.

## Configuring ChartMogul as a Source

In the [Sources](https://app.nekt.ai/sources) tab, click on the "Add source" button located on the top right of your screen. Then, select the ChartMogul option from the list of connectors.

Click **Next** and you'll be prompted to add your access.

### 1. Add account access

The connector signs in with a ChartMogul **API key**. To create one, in ChartMogul open **Profile > View Profile**, choose **API Keys** in the sidebar and click **Add API Key**. A key with **read-only** access is enough. We recommend a dedicated key for Nekt, so you can revoke it without affecting other integrations. See [ChartMogul's guide to API keys](https://help.chartmogul.com/article/95-creating-and-managing-api-keys).

The following configurations are available:

* **API Key**: The ChartMogul API key.
* **Start Date**: Earliest date to read for activities (activity date) and first day of the daily metrics. ChartMogul recalculates past activities and metrics whenever your billing data changes (an invoice imported late, a refund, a customer merge, a new billing source), so these streams are read again from this date on every sync. The other streams are always read in full.

Once you're done, click **Next**.

### 2. Select streams

Choose which data streams you want to sync. For faster extractions, select only the streams that are relevant to your analysis. You can select entire groups of streams or pick specific ones.

> Tip: The stream can be found more easily by typing its name.

Select the streams and click **Next**.

### 3. Configure data streams

Customize how you want your data to appear in your catalog. Select the desired layer where the data will be placed, a folder to organize it inside the layer, a name for each table (which will effectively contain the fetched data) and the type of sync.

* **Layer**: choose between the existing layers on your catalog. This is where you will find your new extracted tables as the extraction runs successfully.
* **Folder**: a folder can be created inside the selected layer to group all tables being created from this new data source.
* **Table name**: we suggest a name, but feel free to customize it. You have the option to add a **prefix** to all tables at once and make this process faster!
* **Sync Type**: you can choose between INCREMENTAL and FULL\_TABLE.
  * Incremental: every time the extraction happens, we'll get only the new data, which is good if, for example, you want to keep every record ever fetched.
  * Full table: every time the extraction happens, we'll get the current state of the data, which is good if, for example, you don't want to have deleted data in your catalog.

Once you are done configuring, click **Next**.

### 4. Configure data source

Describe your data source for easy identification within your organization, not exceeding 140 characters.

To define your [Trigger](https://docs.nekt.com/runs/scheduling-and-triggers.md), consider how often you want data to be extracted from this source. This decision usually depends on how frequently you need the new table data updated (every day, once a week, or only at specific times).

Optionally, you can define some additional settings:

* Configure Delta Log Retention and determine for how long we should store old states of this table as it gets updated. Read more about this resource [here](https://docs.nekt.com/get-started/core-concepts/resource-control).
* Determine when to execute an **Additional [Full Sync](https://docs.nekt.com/get-started/core-concepts/types-of-sync#additional-full-sync)**. This will complement the incremental data extractions, ensuring that your data is completely synchronized with your source every once in a while.

Once you are ready, click **Next** to finalize the setup.

### 5. Check your new source

You can view your new source on the [Sources](https://app.nekt.ai/sources) page. If needed, manually trigger the source extraction by clicking on the arrow button. Once executed, your data will appear in your Catalog.

> [!WARNING]
>
> For you to be able to see it on your [Catalog](https://app.nekt.ai/catalog), you need at least one successful source run.

# Streams and Fields

## Available streams

The table below lists every stream, its **slug** (the exact identifier to pass when creating the source via API) and a short description.

| Stream | Slug | Sync | Description |
| - | - | - | - |
| Customers | `customers` | Full table | Customers and leads, with current MRR, ARR and their lead, trial and subscriber statuses. |
| Subscriptions | `subscriptions` | Full table | Subscriptions of every customer, with current MRR, ARR, plan, quantity and status. |
| Data Sources | `data_sources` | Full table | Billing systems and custom imports that feed the account. |
| Plans | `plans` | Full table | Subscription plans of every source. |
| Plan Groups | `plan_groups` | Full table | Plan groups (sets of plans reported together). |
| Plan Group Plans | `plan_group_plans` | Full table | Which plans belong to each plan group. |
| Invoices | `invoices` | Full table | Invoices, with their line items and transactions as JSON. |
| Invoice Line Items | `invoice_line_items` | Full table | One row per invoice line item (subscription, one-time and trial charges). |
| Invoice Transactions | `invoice_transactions` | Full table | One row per payment or refund attempt of an invoice. |
| Activities | `activities` | Full table | Every MRR movement: new business, expansion, contraction, churn and reactivation. |
| Key Metrics (daily) | `metrics_daily` | Full table | MRR, ARR, churn rates, LTV, active customers, ASP and ARPA for every day. |
| MRR Movements (daily) | `mrr_movements_daily` | Full table | MRR for every day, broken down into new business, expansion, contraction, churn and reactivation. |

> [!NOTE]
>
> Amounts come in **cents**, as ChartMogul sends them: divide by 100 to get the value in the account currency (or, for invoices, in the invoice currency). Nested information (customer attributes, address, custom attributes, edit history, validation errors) comes as JSON text.

## Fields by stream

### Customers and subscriptions

> **Customers**
>
> Customers and leads of your ChartMogul account, with their current MRR and ARR and their lead, trial and subscriber statuses. Read in full on every sync.
>
> Table: `customers` · Primary key: `uuid` · Sync: Full table
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `uuid` | String | ChartMogul UUID of the customer (cus\_ prefix). |
> | `id` | Integer | Internal ChartMogul ID of the customer. |
> | `external_id` | String | Identifier of the customer in the billing system (or as given on import). |
> | `external_ids` | Array of strings | External identifiers of every customer record merged into this customer. |
> | `data_source_uuid` | String | ChartMogul UUID of the source of this customer. |
> | `data_source_uuids` | Array of strings | ChartMogul UUIDs of every source contributing data to this customer (merged customers). |
> | `name` | String | Name of the customer (deprecated by ChartMogul in favour of contacts). |
> | `email` | String | E-mail of the customer (deprecated by ChartMogul in favour of contacts). |
> | `company` | String | Company name of the customer. |
> | `status` | String | Combined lead or subscription status: New Lead, Working Lead, Qualified Lead, Unqualified Lead, Active, Past Due or Cancelled. |
> | `lead_created_at` | Datetime | When the customer became a lead. |
> | `free_trial_started_at` | Datetime | When the customer started a free trial. |
> | `lead_status` | String | Lead status: New Lead, Working Lead, Qualified Lead or Unqualified Lead. |
> | `free_subscriber_status` | String | Free subscriber status, e.g. Active Free Subscriber or Never a Free Subscriber. |
> | `paid_subscriber_status` | String | Paid subscriber status: Active Paid Subscriber, Past-Due Subscriber, Paused Subscriber, Cancelled Subscriber or Never a Paid Subscriber. |
> | `trial_subscriber_status` | String | Trial status, e.g. Active Free Trial, Expired Paid Trial or Never had Trial. |
> | `usage_subscriber_status` | String | Usage-based subscriber status (only for accounts with usage-based subscriptions). |
> | `customer_since` | Datetime | When the customer first started paying for a subscription. |
> | `country` | String | Country of the customer's address. |
> | `state` | String | US state of the customer (two-letter code). |
> | `city` | String | City of the customer's address. |
> | `zip` | String | Zip code of the customer's address. |
> | `attributes` | String (JSON) | Customer attributes: tags, Stripe metadata and custom attributes (JSON object). |
> | `address` | String (JSON) | Address of the customer: address\_zip, city, state, country (JSON object). |
> | `mrr` | Number | Current monthly recurring revenue of the customer, in cents of the account currency (divide by 100). |
> | `arr` | Number | Current annual run rate of the customer, in cents of the account currency (divide by 100). |
> | `billing_system_url` | String | Link to the customer in the billing system, when available. |
> | `chartmogul_url` | String | Link to the customer's page in ChartMogul (needs a ChartMogul login). |
> | `billing_system_type` | String | Billing system the customer was imported from, e.g. Stripe or Custom. |
> | `currency` | String | Currency of the MRR/ARR values. |
> | `currency_sign` | String | Symbol of the currency, e.g. \$. |
> | `owner` | String (JSON) | Team member responsible for the customer relationship. |
> | `website_url` | String | Website of the customer. |
> | `last_seen` | Datetime | When the customer was last active, across all associated contacts. |

> **Subscriptions**
>
> Subscriptions of every customer, with current MRR, ARR, plan, quantity and status. ChartMogul only lists subscriptions customer by customer, so this stream makes one request per customer. Read in full on every sync.
>
> Table: `subscriptions` · Primary key: `uuid` · Sync: Full table
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `uuid` | String | ChartMogul UUID of the subscription. |
> | `customer_uuid` | String | ChartMogul UUID of the customer that owns the subscription. |
> | `id` | Integer | ChartMogul's numeric identifier of the subscription. |
> | `external_id` | String | Identifier of the subscription in the billing system. |
> | `subscription_set_external_id` | String | Identifier of the subscription set this subscription belongs to, if any. |
> | `subscription_set_uuid` | String | ChartMogul UUID of the subscription set this subscription belongs to, if any. |
> | `plan` | String | Name of the billing plan of the subscription. |
> | `quantity` | Number | Quantity of the plan purchased. |
> | `mrr` | Number | Current monthly recurring revenue of the subscription, in cents of the account currency (divide by 100). |
> | `arr` | Number | Current annual run rate of the subscription (MRR x 12), in cents of the account currency. |
> | `status` | String | Current status of the subscription: active or inactive. |
> | `billing_cycle` | String | Billing cycle unit: day, month or year. |
> | `billing_cycle_count` | Integer | Number of billing cycle units between two billings. |
> | `start_date` | Datetime | When the subscription started. |
> | `end_date` | Datetime | When the subscription runs out, based on the payments made so far. |
> | `currency` | String | Currency of the MRR/ARR values. |
> | `currency_sign` | String | Symbol of the currency, e.g. \$. |
> | `custom_attributes` | String (JSON) | Custom attributes set on the subscription (JSON object). |

### Plans and sources

> **Data Sources**
>
> Billing systems and custom imports that feed your ChartMogul account.
>
> Table: `data_sources` · Primary key: `uuid` · Sync: Full table
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `uuid` | String | ChartMogul UUID of the source (ds\_ prefix). |
> | `name` | String | Name of the source. |
> | `system` | String | Billing system of the source, e.g. Stripe, Recurly, or Custom for sources fed through the API. |
> | `created_at` | Datetime | When the source was created in ChartMogul. |
> | `status` | String | Import status: working/idle for custom sources; never\_imported/importing/import\_complete for ChartMogul-maintained integrations. |
> | `auto_churn_subscription_setting` | String (JSON) | How past-due subscriptions of this source are handled (JSON object, as returned by ChartMogul). |
> | `invoice_handling_setting` | String (JSON) | Invoice handling configuration of this source (JSON object, as returned by ChartMogul). |

> **Plans**
>
> Subscription plans of every source, with their billing interval.
>
> Table: `plans` · Primary key: `uuid` · Sync: Full table
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `uuid` | String | ChartMogul UUID of the plan (pl\_ prefix). |
> | `data_source_uuid` | String | ChartMogul UUID of the source (billing system) the plan belongs to. |
> | `name` | String | Name of the plan. |
> | `interval_count` | Integer | Number of interval units between two billings (e.g. 3 with interval\_unit 'month' = billed every 3 months). |
> | `interval_unit` | String | Unit of the billing interval: day, month or year. |
> | `external_id` | String | Identifier of the plan in the billing system (or as given when the plan was created). |

> **Plan Groups**
>
> Plan groups (sets of plans reported together).
>
> Table: `plan_groups` · Primary key: `uuid` · Sync: Full table
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `uuid` | String | ChartMogul UUID of the plan group (plg\_ prefix). |
> | `name` | String | Name of the plan group. |
> | `plans_count` | Integer | Number of plans in the plan group. |

> **Plan Group Plans**
>
> Which plans belong to each plan group: one row per plan group and plan.
>
> Table: `plan_group_plans` · Primary key: `plan_group_uuid`, `uuid` · Sync: Full table
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `plan_group_uuid` | String | ChartMogul UUID of the plan group (plg\_ prefix). |
> | `uuid` | String | ChartMogul UUID of the plan (pl\_ prefix). |
> | `data_source_uuid` | String | ChartMogul UUID of the source (billing system) the plan belongs to. |
> | `name` | String | Name of the plan. |
> | `interval_count` | Integer | Number of interval units between two billings (e.g. 3 with interval\_unit 'month' = billed every 3 months). |
> | `interval_unit` | String | Unit of the billing interval: day, month or year. |
> | `external_id` | String | Identifier of the plan in the billing system (or as given when the plan was created). |

### Invoices

> **Invoices**
>
> Invoices imported into ChartMogul: the valid, enabled invoices that ChartMogul uses for its metrics. Line items and transactions are also available one per row in the next two streams.
>
> Table: `invoices` · Primary key: `uuid` · Sync: Full table
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `uuid` | String | ChartMogul UUID of the invoice (inv\_ prefix). |
> | `customer_uuid` | String | ChartMogul UUID of the customer the invoice belongs to. |
> | `data_source_uuid` | String | ChartMogul UUID of the source of the invoice, when returned. |
> | `external_id` | String | Identifier of the invoice in the billing system. |
> | `customer_external_id` | String | Identifier of the customer in the billing system. |
> | `date` | Datetime | When the invoice was raised. |
> | `due_date` | Datetime | When the invoice is due. |
> | `currency` | String | Three-letter currency code of the invoice. |
> | `collection_method` | String | How payment is collected: automatic or manual. |
> | `status` | String | Invoice status: open, paid, refunded, voided or written\_off. |
> | `disabled` | Boolean | Whether the invoice was disabled in ChartMogul. |
> | `disabled_at` | Datetime | When the invoice was disabled. |
> | `disabled_by` | String | E-mail of the team member who disabled the invoice. |
> | `user_created` | Boolean | Whether a team member created the invoice by hand for an automatic source. |
> | `edit_history_summary` | String (JSON) | Summary of manual edits made in ChartMogul (values\_changed, latest\_edit\_author, latest\_edit\_performed\_at; JSON object). |
> | `errors` | String (JSON) | Validation errors recorded when the data was ingested, by attribute (JSON object; empty when valid). |
> | `line_items` | String (JSON) | Line items of the invoice (JSON array; also available one per row in invoice\_line\_items). |
> | `transactions` | String (JSON) | Payments and refunds of the invoice (JSON array; also available one per row in invoice\_transactions). |

> **Invoice Line Items**
>
> Every line item of every invoice (subscription, one-time and trial charges), with amounts, discounts, taxes, fees and the service period.
>
> Table: `invoice_line_items` · Primary key: `uuid` · Sync: Full table
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `uuid` | String | ChartMogul UUID of the line item (li\_ prefix). |
> | `invoice_uuid` | String | ChartMogul UUID of the invoice the line item belongs to. |
> | `customer_uuid` | String | ChartMogul UUID of the customer of the invoice. |
> | `external_id` | String | Identifier of the line item in the billing system. |
> | `type` | String | Line item type: subscription, one\_time or trial. |
> | `description` | String | Description of a one\_time line item. |
> | `amount_in_cents` | Number | Amount charged for the service period, after discounts and taxes, in cents of the invoice currency. |
> | `quantity` | Number | Quantity billed. |
> | `discount_code` | String | Code of the discount applied. |
> | `discount_amount_in_cents` | Number | Discount amount, in cents. |
> | `discount_description` | String | Description of the discount. |
> | `tax_amount_in_cents` | Number | Tax amount, in cents. |
> | `transaction_fees_in_cents` | Number | Transaction fees, in cents. |
> | `transaction_fees_currency` | String | Currency of the transaction fees. |
> | `account_code` | String | Accounting code of the line item. |
> | `plan_uuid` | String | ChartMogul UUID of the plan of the subscription. |
> | `plan_external_id` | String | Identifier of the plan in the billing system. |
> | `subscription_uuid` | String | ChartMogul UUID of the subscription charged. |
> | `subscription_external_id` | String | Identifier of the subscription in the billing system. |
> | `subscription_set_external_id` | String | Identifier of the subscription set the subscription belongs to, if any. |
> | `prorated` | Boolean | Whether this is a prorated charge. |
> | `proration_type` | String | Type of proration: differential, full, differential\_mrr or differential\_always. |
> | `service_period_start` | Datetime | Start of the service period charged. |
> | `service_period_end` | Datetime | End of the service period charged. |
> | `event_order` | Integer | Order in which events at the same timestamp are processed. |
> | `balance_transfer` | Boolean | Whether this line item returns value to the customer balance. |
> | `disabled` | Boolean | Whether the line item was disabled in ChartMogul. |
> | `disabled_at` | Datetime | When the line item was disabled. |
> | `disabled_by` | String | E-mail of the team member who disabled the line item. |
> | `user_created` | Boolean | Whether a team member created the line item by hand for an automatic source. |
> | `edit_history_summary` | String (JSON) | Summary of manual edits made in ChartMogul (values\_changed, latest\_edit\_author, latest\_edit\_performed\_at; JSON object). |
> | `errors` | String (JSON) | Validation errors recorded when the data was ingested, by attribute (JSON object; empty when valid). |

> **Invoice Transactions**
>
> Every payment and refund attempt of every invoice.
>
> Table: `invoice_transactions` · Primary key: `uuid` · Sync: Full table
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `uuid` | String | ChartMogul UUID of the transaction (tr\_ prefix). |
> | `invoice_uuid` | String | ChartMogul UUID of the invoice the transaction belongs to. |
> | `customer_uuid` | String | ChartMogul UUID of the customer of the invoice. |
> | `external_id` | String | Identifier of the transaction in the billing system. |
> | `type` | String | Transaction type: payment or refund. |
> | `date` | Datetime | When the transaction was attempted. |
> | `result` | String | Result of the attempt: successful or failed. |
> | `amount_in_cents` | Number | Amount partially paid or refunded, in cents (empty when the whole invoice amount). |
> | `transaction_fees_in_cents` | Number | Fees paid to the billing provider or payment processor, in cents. |
> | `transaction_fees_currency` | String | Currency of the transaction fees. |
> | `disabled` | Boolean | Whether the transaction was disabled in ChartMogul. |
> | `disabled_at` | Datetime | When the transaction was disabled. |
> | `disabled_by` | String | E-mail of the team member who disabled the transaction. |
> | `user_created` | Boolean | Whether a team member created the transaction by hand for an automatic source. |
> | `edit_history_summary` | String (JSON) | Summary of manual edits made in ChartMogul (values\_changed, latest\_edit\_author, latest\_edit\_performed\_at; JSON object). |
> | `errors` | String (JSON) | Validation errors recorded when the data was ingested, by attribute (JSON object; empty when valid). |

### Activities and metrics

> **Activities**
>
> Every MRR movement of your account: new business, expansion, contraction, churn and reactivation, per customer. Read in full, from the Start Date, on every sync.
>
> Table: `activities` · Primary key: `uuid` · Sync: Full table
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `uuid` | String | ChartMogul UUID of the activity. |
> | `date` | Datetime | When the activity occurred. |
> | `type` | String | Activity type: new\_biz, expansion, contraction, churn or reactivation. |
> | `description` | String | Description of the activity, e.g. 'purchased the Silver plan'. |
> | `activity_mrr_movement` | Number | Change in MRR caused by the activity (positive or negative), in cents of the account currency. |
> | `activity_mrr` | Number | MRR of the customer after the activity, in cents of the account currency. |
> | `activity_arr` | Number | ARR of the customer after the activity, in cents of the account currency. |
> | `currency` | String | Account currency of the amounts, e.g. USD. |
> | `customer_uuid` | String | ChartMogul UUID of the customer. |
> | `customer_name` | String | Name of the customer. |
> | `customer_external_id` | String | Identifier of the customer in the billing system. |
> | `subscription_external_id` | String | Identifier of the subscription (in the billing system) on the activity date. |
> | `subscription_set_external_id` | String | Identifier of the subscription set, if any. |
> | `plan_external_id` | String | Identifier of the plan related to the activity. |
> | `billing_connector_uuid` | String | ChartMogul UUID of the source (billing system) of the activity. |

> **Key Metrics (daily)**
>
> All key metrics for every day since the Start Date: MRR, ARR, customer and net MRR churn rates, LTV, active customers, ASP and ARPA. Read in full, from the Start Date, on every sync.
>
> Table: `metrics_daily` · Primary key: `date` · Sync: Full table
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `date` | Date | Day the values refer to (end of the daily interval). |
> | `mrr` | Number | Monthly recurring revenue at the end of the day, in cents of the account currency (divide by 100). |
> | `mrr_percentage_change` | Number | Percentage change of MRR from the previous day. |
> | `arr` | Number | Annual run rate at the end of the day, in cents of the account currency (divide by 100). |
> | `arr_percentage_change` | Number | Percentage change of ARR from the previous day. |
> | `customer_churn_rate` | Number | Customer churn rate, as a percentage. |
> | `customer_churn_rate_percentage_change` | Number | Percentage change of the customer churn rate from the previous day. |
> | `mrr_churn_rate` | Number | Net MRR churn rate, as a percentage. |
> | `mrr_churn_rate_percentage_change` | Number | Percentage change of the net MRR churn rate from the previous day. |
> | `ltv` | Number | Customer lifetime value, in cents of the account currency (divide by 100). |
> | `ltv_percentage_change` | Number | Percentage change of LTV from the previous day. |
> | `customers` | Integer | Number of active customers at the end of the day. |
> | `customers_percentage_change` | Number | Percentage change of active customers from the previous day. |
> | `asp` | Number | Average sale price, in cents of the account currency (divide by 100). |
> | `asp_percentage_change` | Number | Percentage change of ASP from the previous day. |
> | `arpa` | Number | Average revenue per account, in cents of the account currency (divide by 100). |
> | `arpa_percentage_change` | Number | Percentage change of ARPA from the previous day. |

> **MRR Movements (daily)**
>
> MRR for every day since the Start Date, broken down into new business, expansion, contraction, churn and reactivation. Read in full, from the Start Date, on every sync.
>
> Table: `mrr_movements_daily` · Primary key: `date` · Sync: Full table
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `date` | Date | Day the values refer to (end of the daily interval). |
> | `mrr` | Number | Monthly recurring revenue at the end of the day, in cents of the account currency (divide by 100). |
> | `percentage_change` | Number | Percentage change of MRR from the previous day. |
> | `mrr_new_business` | Number | New MRR from new customers during the day, in cents of the account currency (divide by 100). |
> | `mrr_expansion` | Number | New MRR from existing customers (e.g. upgrades) during the day, in cents of the account currency (divide by 100). |
> | `mrr_contraction` | Number | Decrease in MRR during the day, excluding cancellations (negative), in cents of the account currency (divide by 100). |
> | `mrr_churn` | Number | Decrease in MRR from customers who cancelled during the day (negative), in cents of the account currency (divide by 100). |
> | `mrr_reactivation` | Number | MRR from customers who had cancelled and came back during the day, in cents of the account currency (divide by 100). |

## Implementation Notes

### Data Quality Considerations

* **Every stream is read in full on every sync.** ChartMogul has no "changed since" filter for customers, plans or invoices, and it recalculates activities and metrics for past days, with no time limit, whenever your billing data changes. A full read is the only way to always match what ChartMogul shows: an invoice paid or refunded later, a customer that churned, an activity added months in the past or replaced after a recalculation, a corrected MRR value.
* **A sync never loads half a stream**: every stream is read completely before anything is loaded, so a sync that fails halfway leaves the previous table in place. If a stream that had records comes back completely empty, the sync stops instead of emptying the table (Plan Group Plans and Invoice Transactions excepted, as they can legitimately be empty). If ChartMogul leaves out a day in the middle of the daily metrics, the sync stops instead of saving a table with a missing day. Days before your account's history starts, and today or yesterday when your ChartMogul time zone is behind UTC, are simply not in the table yet.
* **Invoices**: only valid, enabled invoices are read, the same ones ChartMogul uses for its metrics. Invoices with import errors or disabled in ChartMogul do not appear.
* **Daily metrics** follow your ChartMogul account's time zone and include today, whose values change until the day ends. Every percentage change is relative to the previous day.

### API Limits & Performance

* ChartMogul allows 40 requests per second. The connector sends at most 20 per second, one at a time, and waits when ChartMogul asks it to slow down.
* Lists are read in pages of 200 records.
* Subscriptions are only available customer by customer, so the Subscriptions stream makes one request per customer, one after the other. Expect roughly 35 to 50 minutes for 10,000 customers and several hours for 100,000. While it runs, the sync log shows how many customers were read and an estimate of the time left. For very large accounts (for example B2C, with hundreds of thousands of customers), deselect Subscriptions or schedule the source with long runs in mind: the Customers stream already has each customer's current MRR and ARR.
* The daily metrics are read in blocks of 180 days, about 3 requests per year of history for each of the two metrics streams.

## Troubleshooting

| Error or symptom | What it means | What to do |
| :- | :- | :- |
| "ChartMogul rejected the API key" | The key is wrong, was deleted or was deactivated. | Create or copy a key in **Profile > View Profile > API Keys** and update the source. |
| "The ChartMogul API key of this source is not allowed to read ..." | The key has no access to that data. | Use a key of a team member with access to it, or deselect that stream. |
| "ChartMogul returned no ... records at all, although the previous sync read N" | A stream that had records came back empty, so the sync stopped instead of emptying the table. | If the data really was removed in ChartMogul, run a full sync of the source to accept the empty table; otherwise deselect that stream. |
| "N customer(s) were removed or merged in ChartMogul while this sync was running" | Customers were deleted or merged between reading the customer list and reading their subscriptions, so their subscriptions are missing from this sync. | Nothing to fix in ChartMogul. The next sync reads the subscriptions again (a merged customer's under the customer it was merged into); run the source again if you need the table complete now. |
| "ChartMogul could not find the subscriptions of N of M customers" | Too many customers disappeared during one sync to be normal, so the sync stopped. | Run the source again; if it repeats, contact Nekt support. |
| "ChartMogul did not return the subscriptions of a customer that still exists" | ChartMogul answered "not found" for an existing customer. | Run the source again; if it repeats, contact Nekt support. |
| "N plan group(s) were deleted in ChartMogul while this sync was running" | Plan groups were deleted during the sync. | No action needed; the next sync no longer sees them. |
| "ChartMogul left N day(s) out of the daily ... values" | ChartMogul left out days in the middle of the metrics history, so the sync stopped. | Run the source again; if it repeats, contact Nekt support. |
| "ChartMogul is limiting how fast this sync may read" | ChartMogul's rate limit was reached; the connector is waiting. | No action needed. If it happens often, check other integrations using the same ChartMogul account. |
| "ChartMogul kept failing while reading ..." or "ChartMogul did not answer ..." | The ChartMogul API returned errors or timed out several times in a row. | Run the source again later. |
| "ChartMogul answered ... in a format this connector does not recognise" | The ChartMogul API changed. | Contact Nekt support. |

## Skills for agents

<Snippet file="agent-skills-intro.mdx" />

> **[Download ChartMogul skills file](https://docs.nekt.com/sources/chartmogul.md)**
>
> ChartMogul connector documentation as plain markdown, for use in AI agent contexts.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.