Importing billing data using CSV – Help Center

You’ll need to be an Admin or Owner in ChartMogul to add and manage sources. Read more about user roles and permissions.

To get accurate subscription and cashflow metrics, add each of your billing systems as a source in ChartMogul. Add a custom data source and import billing data using CSV when:

You use a supported billing system but have customers who are billed outside of this system.
Your billing system is not supported by ChartMogul. Billing data can also be added manually or using the Import API.
You want to import historical data.

Here’s what we cover in this article:

Resources and further reading:

Learn more about importing subscription data.

How it works

Upload CSV files to a custom data source. To create a new custom data source, navigate to Data Platform > Sources and click Add a Source. Then, select Custom Data Source. Enter a name and click Next.

CSV files must be uploaded in a specific order: import customers and plans, and wait for all rows to be processed. Once all customers and plans have been imported successfully, upload invoices, invoice line items, transactions, and cancellations.

To import data, select the section for the data you want to import (e.g., Customers) and click Import CSV. Then, upload the corresponding CSV file. Repeat these steps for each section in the custom data source.

After data is uploaded and processed, it will appear in rows in the custom data source. By default, data is filtered to the last uploaded CSV file. View a different data set by using the Filter by CSV import filter. Remove the filter to view all data.

Formatting CSV files

To import subscription data into ChartMogul using CSV, it must be in a specific format. Prepare separate CSV files for each dataset (e.g., Customers, Plans, Invoices, etc.) as they appear in Data Platform.

To get started, navigate to Data Platform and click Export CSV. ChartMogul gives you the option to export the dataset you’re viewing, or all data.

Or download a sample CSV file for the dataset, which includes the basic columns you’ll need to get started:

Or, download all sample files as a zip.

CSV files should be in either ASCII or UTF-8 Unicode file format.

Customers

When importing 5,000 customers or more, we recommend waiting one hour for all data to be processed before importing the remaining datasets.

Column Name	Description	Field Type	Value
Name	Name of the customer — typically the first and last name of the primary contact for this client	Required	Accepts up to 255 alphanumeric and special characters
Email	Email address for this customer	Optional	A valid email address
Company	Company name is required when the customer is an organization and not an individual	Optional	Accepts up to 255 alphanumeric and special characters
Country	The customer’s country	Optional	Specify region name or region code. Field is not case-sensitive.
State	The customer’s state in the US	Optional	US States only. Field is not case-sensitive.
City	The customer’s city	Optional	Accepts up to 255 alphanumeric and special characters
Zip	The customer’s postal code	Optional	Accepts up to 255 alphanumeric and special characters
External ID	The unique identifier for the customer — typically the customer ID from your billing system. Column is `Customer ID` in Data Platform.	Required	Accepts up to 255 alphanumeric and special characters. Must be unique. Value is permanent and cannot be changed.
Lead created at	Date when the lead was created. Learn more about tracking leads and trials.	Optional	Format date as `YYYY-MM-DD`
Free trial started at	Date when the free trial started. Learn more about tracking leads and trials.	Optional	Format date as `YYYY-MM-DD`

Plans

Column Name	Description	Field Type	Value
Name	The plan’s name	Required	Accepts up to 255 alphanumeric and special characters
Interval count	Frequency of billing interval. Value is permanent and cannot be changed.	Required	A positive integer greater than 0. To understand interval unit and interval count, here are some examples: For a weekly plan, specify `day` as the interval unit and set the interval count to 7. For a quarterly plan, specify `month` as the interval and set the interval count to 3. For a yearly plan, specify `month` as the interval unit and set the interval count to 12. Alternatively, set `year` as the interval unit, and set the Interval count to 1.
Interval unit	The unit of billing interval. Value is permanent and cannot be changed.	Required	Specify either `Day`, `Month`, or `Year`. Field is not case-sensitive.
Plan ID	A unique identifier for the plan. Typically a plan ID from your billing system. Value is permanent and cannot be changed.	Required	Must be unique, such as your billing system's plan ID. Accepts up to 255 alphanumeric and special characters.

Invoices

Column Name	Description	Field Type	Value
Customer external ID	The unique identifier for the customer — typically the customer ID from your billing system. Column is `Customer` in Data Platform.	Required	Accepts up to 255 alphanumeric and special characters
Invoice external ID	A unique identifier for the invoice — typically the invoice number in your billing system. Column is `Invoice ID` in Data Platform.	Required	Must be unique. Accepts up to 255 alphanumeric and special characters
Invoiced date	Date on which the invoice was raised	Required	Format date as `YYYY-MM-DD`
Due Date	Date upon which the invoice must be paid	Optional	Format date as `YYYY-MM-DD`
Currency	The customer’s billing currency	Required	Three-letter ISO code of the currency. Field is case-sensitive.

Immediately after importing invoices, ChartMogul will categorize the Import Status as Failed. ChartMogul categorizes an invoice as Processed when invoice line items are successfully added.

Invoice Line Items

Column Name	Description	Field Type	Value
Invoice external ID	The unique identifier for the invoice. This is typically the invoice number in your billing system. Column is `Invoice` in Data Platform.	Required	Should be unique. Accepts up to 255 alphanumeric and special characters.
External ID	The unique identifier for the line item. Column is `Line Item ID` in Data Platform.	Optional	Should be unique. Accepts up to 255 alphanumeric and special characters.
Subscription external ID	The unique identifier for the subscription. This is typically the subscription ID in your billing system. Column is `Subscription ID` in Data Platform.	Required for subscriptions	Should be unique for this source. Accepts up to 255 alphanumeric and special characters.
Subscription set external ID	The unique identifier for subscriptions with multiple components. Column is `Subscription Set ID` in Data Platform.	Optional	Should be unique for this source. Accepts up to 255 alphanumeric and special characters.
Type	The type of charge, subscription or non-recurring (one time)	Required	Specify either `Subscription` or `OneTime`. Field is case-sensitive.
Amount in cents	The final amount billed towards the invoice line item, in cents. Column is `Amount` in Data Platform.	Required	Accepts only numerical characters (no decimal point). Use a negative value to add credit to a customer’s account.
Plan	Plan ID for this subscription	Required for subscriptions	The plan’s External ID found by navigating to Profile > Admin > Plans and locating the `External ID` in the table.
Service period start	The start date of the subscription’s service period	Required for subscriptions	Format date as `YYYY-MM-DD`
Service period end	The end date of the subscription’s service period	Required for subscriptions	Format date as `YYYY-MM-DD`
Quantity	Quantity for this line item. Quantity value does not impact calculation of MRR.	Optional	Accepts any non-zero integer. Defaults to 1. Non-prorated line items cannot have a negative quantity.
Proration	Specify if this charge is prorated.	Required	Specify either `TRUE` (`true`, `1`) or `FALSE` (`false`, `0`).
Proration type	Type of prorated charge. Learn about different proration types.	Optional	Specify `differential`, `full`, or `differential_mrr`. If not specified, this defaults to `differential`. Field is case-sensitive.
Discount code	A reference code for the discount	Optional	Accepts up to 64 alphanumeric and special characters.
Discount amount	The amount discounted when a discount is applied to this invoice line item	Optional	The amount in cents. Accepts only numerical characters (no decimal point).
Tax amount	The amount of tax applied to the invoice line item	Optional	The amount in cents. Accepts only numerical characters (no decimal point).
Description	A description of the services provided for one-time transactions, visible from a customer’s record.	Optional	Accepts up to 255 alphanumeric and special characters.
Discount description	A description of the discount.	Optional	Accepts up to 255 alphanumeric and special characters.
Transaction fee	Transaction fees from your billing system or payment provider. Learn more.	Optional	The amount in cents. Accepts only numerical characters (no decimal point).
Transaction fees currency	The currency of transaction fees.	Optional	Three-letter ISO code of the currency. Field is case-sensitive.
Account Code	The unique account code of the line item used for the purposes of accounting and revenue recognition. Also called 'account number' in some systems. Currently not visible in-app and only supported for Xero.	Optional	Must be unique, such as an account number. Accepts a maximum of 30 alphanumeric characters.
Event order	Specifies the order ChartMogul processes line items with the same service period start date. Learn more.	Optional	Must be a non-zero integer.
Balance transfer	Indicates that the amount should be credited to or debited from the customer’s balance. Positive values represent credit added to the customer’s account. Negative values represent credit used as payment. This applies only to non-recurring line items.	Optional	Specify either `TRUE` (`true`, `1`) or `FALSE` (`false`, `0`).

Transactions

The Transactions CSV records attempted payments and refunds for invoices and does not provide a column for transaction amount. Therefore, all invoices are understood to have been either paid or refunded in full.

Column Name	Description	Field Type	Value
Invoice external ID	The unique identifier for the invoice. This is typically the invoice number in your billing system. Column is `Invoice` in Data Platform.	Required	Must be unique. Accepts up to 255 alphanumeric and special characters.
External ID	The unique identifier for this transaction. This is typically the transaction ID in your billing system or payment gateway. Column is `Transaction ID` in Data Platform.	Optional	Must be unique. Accepts up to 255 alphanumeric and special characters.
Type	The transaction’s type	Required	Specify either `payment` or `refund`. Field is case-sensitive.
Result	The outcome of the transaction	Required	Specify either `successful` or `failed`. Field is case-sensitive.
Date	The date of the attempted transaction	Required	Format date as `YYYY-MM-DD`

Subscription Events

Column Name	Description	Field Type	Value
Customer external ID	The unique identifier for the customer — typically the customer ID from your billing system. Column is `Customer` in Data Platform.	Required	Accepts up to 255 alphanumeric and special characters
Subscription external ID	The unique identifier for the subscription. Typically the subscription ID in your billing system. Column is `Subscription ID` in Data Platform.	Required for all subscription event types except `subscription_event_retracted`.	Should be unique for this data source. Accepts up to 255 alphanumeric and special characters.
External ID	A unique identifier for the event, typically provided by your billing system. Column is `Event ID` in Data Platform.	Optional	Must be unique for this data source. Accepts up to 255 alphanumeric and special characters.
Event Type	The change in a subscription is classified as an event type. Column is `Subscription Event Type` in Data Platform.	Required	Specify an event type. Field is case-sensitive. `subscription_cancellation_scheduled` `subscription_cancelled` `subscription_event_retracted` `subscription_start` `subscription_start_scheduled` `subscription_update_scheduled` `subscription_updated`
Retracted event ID	A unique identifier required for retracted events	Optional	Accepts up to 255 alphanumeric and special characters
Date	The date the subscription change was requested or triggered	Required	Format date as `YYYY-MM-DD`
Effective Date	The date the subscription change will be implemented	Required	Format date as `YYYY-MM-DD`
Plan external ID	The unique identifier for this plan, typically provided by your billing system. Column is `Plan` in Data Platform.	Required for `subscription_start`, `subscription_start_scheduled`, `subscription_updated`, and `subscription_update_scheduled` event types.	The plan’s External ID found by navigating to Profile > Admin > Plans and locating the `External ID` in the table.
Currency	The invoice’s currency	Required for `subscription_start`, `subscription_start_scheduled`, `subscription_updated`, and `subscription_update_scheduled` event types.	Three-letter ISO code of the currency. Field is case-sensitive.
Amount in Cents	The final amount billed for the specified quantity after discounts, taxes, and fees have been applied. Column is `Amount` in Data Platform.	Required for `subscription_start`, `subscription_start_scheduled`, `subscription_updated`, and `subscription_update_scheduled` event types.	The amount in cents. Accepts only numerical characters (no decimal point).
Quantity	Quantity of subscription events being billed. Quantity value does not impact CMRR.	Required for `subscription_start`, `subscription_start_scheduled`, `subscription_updated`, and `subscription_update_scheduled` event types.	Can be any non-zero integer. Defaults to 1.

Editing uploaded data in-app

Navigate to Data Platform > Sources, then find and click the source containing the data you’d like to update. Next, select the corresponding record type (Customers, Invoice, Invoice Line Items, Transactions, Subscriptions Events, Subscriptions, or Plans) using the tabs provided.

Finally, click the Edit icon for the row you’d like to update, make the your changes, and click the green checkmark to save.

Alternatively, upload a new CSV file with updated data. When the CSV file includes data you’ve already imported, ChartMogul updates existing rows. When there are additional (new) rows of data in the CSV file, ChartMogul imports them as new data.