Adding billing data in-app with Data Platform – 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 metrics, add all your subscription data as sources in ChartMogul. Add billing data in-app with Data Platform using a custom data source when:

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

Before you begin

Learn more about importing subscription data and how ChartMogul uses your billing data to generate subscriptions and calculate metrics.
Include data in optional fields for deeper insights with segmentation.

Getting started

Start by creating a new, custom data source for the billing data you’ll import:

Navigate to Data Platform > Sources and click Add a Source.
Select Custom Source.
Enter a unique name.
Click Next.

ChartMogul creates your custom data source and a table for each dataset. Learn more about each table:

Customers
Contacts
Plans
Invoices
Invoice Line Items
Transactions
Subscription Events
Subscriptions

Click the green checkmark to add a row of data. Click the edit icon to update a row and green checkmark to submit your changes. To delete a row, click the tick box to select it, and then click Delete Selected Rows.

Customers

To add a new customer, navigate to Customers > New Customer.

Column Name	Description	Field Type	Value
Company Name	Add a company name when the customer is a business and not an individual. To add an individual customer, leave this field blank and add a contact.	Optional	Accepts up to 255 alphanumeric and special characters.
Customer ID	A unique identifier for this customer — typically the customer ID from your billing system. Value is permanent and cannot be changed.	Required	Must be unique. Accepts up to 255 alphanumeric and special characters.
Full name (legacy)	On April 4, 2023 we released ChartMogul CRM. The contact name field on customer records will be phased out as it’s now possible to add contact names to your customer records. Use the Company Name field to store the customer/account name, and add Contact records for people associated with an account. When adding B2C (consumer) customers, leave the Company name field blank and add a single contact to the customer record. If (like many ChartMogul users) you've been storing Company names in this field please contact support.	Optional	Accepts up to 255 alphanumeric and special characters.
Email (legacy)	On April 4, 2023 we released ChartMogul CRM and this field will eventually be phased out. You can now add Contacts (each with their own email address) to your customer records.	Optional	Should be a valid email address.
Country	The customer’s country.	Optional	Choose the country from the drop-down.
State	The customer’s state in the US.	Optional	Choose the state from the drop-down.
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.
Lead created at	The date and time when the lead was created. We use this information to generate lead volume reports.	Optional	Choose the date from the drop-down or enter the date and time manually in the ISO 8601 format. If not set, time defaults to midnight.
Free trial started at	The date and time when the free trial started. We use this information to generate reports of your free trials and trial-to-paid conversions.	Optional	Choose the date from the drop-down or enter the date and time manually in the ISO 8601 format. If not set, time defaults to midnight.

Default sorting for table rows is by time created, which is not visible. This may be different from the order in which you uploaded the data.

Contacts

To add a new contact, navigate to Contacts > New Contact.

Column Name	Description	Field Type	Value
Customer	Customer associated with the contact.	Required	Choose the customer from the drop-down.
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.
Title	The contact’s job title, e.g., CEO.	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.
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. Must end in a domain name (.com, .co.uk, etc) to generate a hyperlink.
Twitter	URL for the contact’s X (formerly known as Twitter) profile.	Optional	Accepts up to 255 alphanumeric and special characters. Must end in .com to generate a hyperlink.
Note	Additional details you wish to add to the customer record.	Optional	Accepts up to 255 alphanumeric and special characters.

Plans

To create a new subscription plan, navigate to Plans > New Plan.

To add a plan, you’ll need to specify the interval unit and interval count. For example:

For a weekly plan, choose Day as the interval unit and set the interval count to 7.
For a quarterly plan, please choose Month as the interval and set the interval count to 3.
For a yearly plan, please choose Month as the interval unit and set the interval count to 12. Alternatively, choose Year as the interval unit and set the interval count to 1.

Column Name	Description	Field Type	Value
Name	Name of the plan.	Required	Accepts up to 255 alphanumeric and special characters.
Plan ID	Unique identifier for the plan. Value is permanent and cannot be changed.	Required	Must be unique. Accepts up to 255 alphanumeric and special characters.
Interval Unit	Unit of billing interval. Value is permanent and cannot be changed.	Required	Choose Day, Month, or Year from the drop-down.
Interval Count	Frequency of billing interval. Value is permanent and cannot be changed.	Required	Accepts up to 255 numeric characters.

Invoices

To create a new invoice, navigate to Invoices > New Invoice.

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

Column Name	Description	Field Type	Value
Customer	Customer name for whom we want to add an invoice.	Required	Choose the customer from the drop-down.
Invoice ID	A unique identifier for the invoice. This is typically the invoice number in your billing system.	Required	Must be unique. Accepts up to 255 alphanumeric and special characters.
Invoice date	The date and time when the invoice was raised.	Required	Choose the invoice date from the drop-down or enter the date and time manually in the ISO 8601 format. If not set, time defaults to midnight.
Due date	The date and time by which the invoice needs to be paid.	Optional	Choose the due date from the drop-down or enter the date and time manually in the ISO 8601 format. If not set, time defaults to midnight.
Currency	The three-letter ISO code of the currency in which the invoice is billed.	Required	Choose the currency from the drop-down.

Invoice Line Items

To add a new invoice line item to an existing invoice, navigate to Invoice Line Items > New Invoice Line Item.

Column name	Description	Field type	Value
Invoice	A unique identifier for the invoice — typically the invoice number in your billing system.	Required	Choose the invoice ID from the drop-down.
Type	Choose if it is a one-time (non-recurring) item or a subscription.	Required	Choose Non-recurring or Subscription from the drop-down.
Amount	The final amount charged towards the invoice line item.	Required	Accepts numbers with up to two decimal places.
Subscription ID	A unique identifier for the subscription — typically the subscription ID in your billing system.	Required	Accepts up to 255 alphanumeric and special characters.
Subscription Set ID	Identifier for subscriptions with multiple components.	Optional	Accepts up to 255 alphanumeric and special characters.
Service Period Start	The date and time when the subscription starts.	Required for subscriptions	Choose the date from the drop-down or enter the date and time manually in the ISO 8601 format. If not set, time defaults to midnight.
Service Period End	The date and time when the subscription ends.	Required for subscriptions	Choose the date from the drop-down or enter the date and time manually in the ISO 8601 format. If not set, time defaults to midnight.
Prorated?	Specifies whether this is a prorated line item.	Required for subscriptions	Choose Yes or No from the drop-down.
Proration Type	Type of prorated charge. Learn about different proration types.	Optional	Choose Differential, Full, or Differential MRR from the drop-down. If not selected, this defaults to Differential.
Plan	Plan for this subscription.	Required for subscriptions	Choose the plan from the drop-down.
Quantity	Subscription quantity for this line item.	Optional	Should be a non-zero integer. Defaults to 1 if not provided.
Transaction Fees	Amount paid to your billing system and/or payment processor for this invoice line item.	Optional	Accepts numbers with up to two decimal places.
Tax Amount	Tax amount is the amount of tax applied to this invoice line item.	Optional	Accepts numbers with up to two decimal places.
Discount Code	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	Accepts numbers with up to two decimal places.
Discount Description	Description of the discount.	Optional	Should be a text string.
Line Item ID	Unique identifier for the invoice line item.	Optional	Must be unique for this data source. Accepts up to 255 alphanumeric and special characters.
Event Order	Specifies the order of processing line items with the same service period start date. Learn more.	Optional	Should be an 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	Choose False or True from the drop-down.

Transactions

To create a new transaction, navigate to Transactions > New Transaction.

Column Name	Description	Field Type	Value
Invoice	The invoice associated with the transaction.	Required	Select the invoice from the drop-down.
Type	The type of transaction: payment or refund.	Required	Select Payment or Refund from the drop-down
Amount	Final transaction amount charged. If left empty, the invoice will be paid in full.	Optional	Accepts numbers with up to two decimal places.
Result	The transaction outcome: successful or failed.	Required	Select Failed or Successful from the drop-down.
Date	Date stamp of the attempted payment.	Required	Choose the date from the drop-down or enter the date and time manually in the ISO 8601 format. If not set, time defaults to midnight.
Transaction ID	Unique identifier for the transaction.	Optional	Must be unique. Accepts up to 255 alphanumeric and special characters.

Subscription Events

Add a new subscription event by navigating to Subscription Events > New Subscription Event.

Column name	Description	Field type	Value
Customer	Customer associated with the subscription.	Required	Choose the customer from the drop-down.
Subscription ID	A unique identifier for the subscription. Typically the subscription ID in your billing system.	Required for all subscription event types except `subscription_ event_ retracted` .	Accepts up to 255 alphanumeric and special characters.
Subscription Set ID	Identifier for subscriptions with multiple components.	Optional	Accepts up to 255 alphanumeric and special characters.
Event ID	A unique identifier for the event, typically provided by your billing system.	Optional	Must be unique for this data source. Accepts up to 255 alphanumeric and special characters.
Subscription Event Type	The change in a subscription is classified as an event type.	Required	Choose the event type from the drop-down.
Retracted Event ID	The Event ID of the subscription event being retracted.	Optional	Must be unique for this data source. Accepts up to 255 alphanumeric and special characters.
Event Date	The date and time when the subscription change was requested or triggered.	Required	Choose the date from the drop-down or enter the date and time manually in the ISO 8601 format. If not set, time defaults to midnight.
Effective Date	The date and time when the subscription change will be implemented.	Required	Choose the date from the drop-down or enter the date and time manually in the ISO 8601 format. If not set, time defaults to midnight.
Plan	A unique identifier for this plan, typically provided by your billing system.	Required for `subscription_ start` , `subscription_ start_ scheduled` , `subscription_ updated` , and `subscription_ update_ scheduled` event types.	Choose the plan from the drop-down.
Currency	The three-letter ISO code of the invoice’s currency.	Required for `subscription_ start` , `subscription_ start_ scheduled` , `subscription_ updated` , and `subscription_ update_ scheduled` event types.	Choose the currency from the drop-down.
Amount	The final amount billed, for the specified quantity, after discounts, taxes, and fees have been applied.	Required for `subscription_ start` , `subscription_ start_ scheduled` , `subscription_ updated` , and `subscription_ update_ scheduled` event types.	Accepts numbers with up to two decimal places.
Tax Amount	Tax applied to a subscription event. Defaults to zero. If specified, tax is excluded from CMRR.	Optional	Accepts numbers with up to two decimal places.
Quantity	Quantity of subscription events being billed. Can be any non-zero integer. Defaults to one. Quantity value does not impact CMRR.	Required for `subscription_ start` , `subscription_ start_ scheduled` , `subscription_ updated` , and `subscription_ update_ scheduled` event types.	Should be a non-zero integer.

Subscriptions

View existing subscription details for each customer from the Subscriptions tab.

View a list of existing subscriptions for each customer. Cancel a subscription by clicking Cancel Subscription.