Importing data using CSV

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

Importing data using CSV is a non-technical method for uploading your business’ data to generate metrics. Learn more about other import methods in Getting started with importing data.

Here’s what we cover in this article:

Once you’ve learned how to add and edit data, review these tables for guidance on importing data:

How to import data using CSV

The datasets you’ll use to import data using CSV depend on how your business stores subscription and billing data: as invoices or as subscriptions. Learn more in Getting started with importing data.

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

To import data, select the section for the data you want to import (e.g., Customers) and click Import CSV. Files must be imported in a specific order. First, upload:

  1. Plans
  2. Customers
  3. Contacts (optional)

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

The remaining datasets you’ll upload depend on how your business stores data: using invoices or as subscriptions. Both options allow you to access subscription analytics and ChartMogul CRM. Learn more about which method is right for your business in Getting started with importing data.

To import using invoice data, upload:

  1. Invoices
  2. Invoice Line Items
  3. Transactions (optional)
  4. Subscription Events

Screenshot highlighting the data tables required for importing invoice data (Customers, Invoices, Invoice Line Items, Subscriptions Events, and Plans) as well as two optional data tables: Contacts and Transactions.

To import using subscription data, upload:

  1. Manual Subscriptions

Screenshot highlighting the data tables required for importing subscription data (Customers, Manual Subscriptions, and Plans) as well as the optional Contacts table.

ChartMogul processes the data and generates subscriptions, which are visible in the Subscriptions tab.

When viewing tables with imported data, data is filtered to view the latest uploaded CSV file. View a different data set by using the Filter by CSV import filter. Remove the filter to view all data.

Sample CSV files

ChartMogul provides sample CSV files as guidance to format your data. Or, upload sample data to see how ChartMogul generates metrics before importing your business’ data.

Download a sample CSV file for a dataset:

Or, download a zip package. Choose the file for the import method you’ll use:

  • Invoice data — contains sample files with customers, contacts, plans, invoices, invoice line items, transactions, and subscription events
  • Manual subscription data — contains sample files with customers, contacts, plans, and manual subscriptions

If your account has existing data, such as sample data, click Export CSV . ChartMogul gives you the option to export the dataset you’re viewing, or all data in the dataset.

The tables below provide guidance to complete each CSV for a successful upload.

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 ChartMogul to process all data before importing the remaining datasets.

Companies or consumers with a potential, current, or past relationship with your business. ChartMogul uses this data to create customer records. This dataset is required.

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

Contacts

Personal and contact details of individuals with a current or past relationship with your business. ChartMogul stores contacts on customer records. This dataset is optional. Import contacts to use ChartMogul CRM.

Column Name Description Field Type Value
Customer External ID The unique identifier for the customer associated with this contact. Required Accepts up to 255 alphanumeric and special characters.
First Name The contact’s first name. Optional Accepts up to 255 alphanumeric and special characters.
Last Name The contact's last name. Optional Accepts up to 255 alphanumeric and special characters.
Email Email address for this contact. Optional

Should follow email format.

Accepts up to 255 alphanumeric and special characters.

Must be unique within the customer record.

Position A number used to order contacts in the customer record, starting with the lowest number. Optional

An integer greater than 0.

If left blank, ChartMogul assigns the next available position to the contact.

Title The contact’s job title, e.g., CEO. Optional Accepts up to 255 alphanumeric and special characters.
Phone Phone number for this contact. Optional Accepts up to 255 alphanumeric and special characters.
LinkedIn URL for the contact’s LinkedIn profile. Optional Accepts up to 255 alphanumeric and special characters.
Twitter URL for the contact’s X (formerly known as Twitter) profile. Optional Accepts up to 255 alphanumeric and special characters.
Note Additional details you wish to add to the customer record. Optional Accepts up to 255 alphanumeric and special characters.

Plans

The name, unique ID, and frequency of the product/services (or sets thereof) you offer on a subscription (recurring) basis. This dataset is required.

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 An 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

When a new invoice is uploaded, ChartMogul categorizes the Import Status as Failed. ChartMogul categorizes an invoice as Processed when invoice line items are successfully uploaded.

The customer name, unique ID, and date for the product/services being billed. Invoices must include invoice line items. ChartMogul uses this data to calculate subscription analytics. This dataset is not required for manual subscriptions.

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

Details of the service (or products) you’ve sold, including customer name, plan (or product), service period, the subscription’s unique ID, and amount billed. ChartMogul uses this data to generate subscriptions. From there, it calculates subscription analytics. This dataset is not required for manual subscriptions.

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 ChartMogul. 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 ChartMogul. 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 ChartMogul. 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 ChartMogul. 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 ChartMogul. 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 Data & Config > Manage > 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.

Attempted payments and refunds to invoices. ChartMogul uses this data to generate cash flow reports. This dataset is not required for manual subscriptions.

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

Any change to a subscription that affects the subscription’s calculated MRR. ChartMogul relies on cancellation events to definitively know when a subscription has ended. Add scheduled events to track Committed Monthly Recurring Revenue (CMRR). This dataset is not required for manual subscriptions.

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 ChartMogul. 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 ChartMogul. Required for all subscription event types except subscription_event_retracted . Should be unique for this 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 ChartMogul. Optional Must be unique for this 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 ChartMogul. 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 ChartMogul. Required for subscription_start, subscription_start_scheduled, subscription_updated, and subscription_update_scheduled event types. The plan’s External ID found by navigating to Data & Config > Manage > 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 ChartMogul. 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.

Manual Subscriptions

Track subscriptions in ChartMogul without uploading invoice data. Learn more. Do not use this dataset when importing data using invoices.

Column Name Description Field Type Value
External ID A unique identifier for the manual subscription event. Column is Event ID in ChartMogul. Optional Must be unique for this source. 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 ChartMogul. Required Should be unique for this source. Accepts up to 255 alphanumeric and special characters.
Customer external ID The unique identifier for the customer — typically the customer ID from your billing system. Column is Customer in ChartMogul. Required Accepts up to 255 alphanumeric and special characters
Plan external ID The unique identifier for this plan, typically provided by your billing system. Column is Plan in ChartMogul. Required for manual_subscription_started and manual_subscription_updated event types The plan’s External ID found by navigating to Data & Config > Manage > Plans and locating the External ID in the table.
Date The date the subscription change was requested or triggered. Column is Event Date in ChartMogul. Required Format date as YYYY-MM-DD.
Effective Date The date the subscription change will be implemented Required Format date as YYYY-MM-DD.
Event Type The change in a subscription is classified as an event type. Column is SubscriptionEvent Type in ChartMogul. Required Specify an event type. Field is case-sensitive.
  • manual_subscription_started
  • manual_subscription_updated
  • manual_subscription_cancelled
Currency The subscription’s currency Required for manual_subscription_started and manual_subscription_updated 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 ChartMogul. Required for manual_subscription_started and manual_subscription_updated event types The amount in cents. Accepts only numerical characters (no decimal point).
Quantity Quantity of manual subscriptions being billed.  Required for manual_subscription_started and manual_subscription_updated event types Can be any non-zero integer.
Report Cash Flow Specify if ChartMogul creates transactions to have the subscription contribute to cash flow reports. This does not impact your billing system. Required Specify either TRUE (true, 1) or FALSE(false, 0).

Editing uploaded data in-app

Once you’ve uploaded data, edit it within ChartMogul.

Navigate to Data & Config > Sources and click the source containing the data you’d like to update. Next, select the dataset using the tabs: Customers, Contacts, Invoices, Invoice Line Items, Transactions, Subscriptions Events, Manual Subscriptions, or Plans. The Subscriptions tab is a record of the subscriptions generated by ChartMogul and cannot be edited.

ChartMogul Data Platform

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

Screencap of editing a row in the Invoice Line Items table.

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.

Was this article helpful?

We’re sorry to hear that. Would you like to share more feedback?


Thanks for your feedback!