Adding billing data manually

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

To get accurate subscription metrics, add all your data sources to ChartMogul. Manually add billing data using a custom data source when:

Here are the steps we cover in this article:

  1. Navigate to Data Platform
  2. Add a new custom data source
  3. Add a customer
  4. Add a plan
  5. Add an invoice
  6. Add invoice line items
  7. Add transactions
  8. Add subscription events
  9. View subscriptions
  10. Understanding how line items and transactions impact different aspects in ChartMogul
  11. Edit existing data

1. Navigate to Data Platform

Go to Data Platform.

2. Add a new custom data source

To create a new custom data source, go to Data Sources > ADD A DATA SOURCE. Then, select Custom Data Source. Create a name and click Next.

The data source has a number of tabs to view and manage each section:

  • Customers
  • Invoices
  • Invoice Line Items
  • Transactions
  • Cancellations
  • Subscriptions
  • Plans

3. Add a customer

To add a new customer navigate to Customers > NEW CUSTOMER.

Enter a Name and unique Customer ID. Complete optional fields such as Company, Email, and Country. Once complete, click the green checkmark to save.

The fields in the customer table and their supported values are summarized in the table below. Include data in optional fields for better segmentation.
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

1. Can have alphanumeric and special characters

2. Should be greater than 0 and less than 255 characters

Company Company name is required when the client is an organization and not an individual. Not required

1. Can have alphanumeric and special characters

2. Should be greater than 0 and less than 255 characters

Email Email address for this customer. Not required Should be a valid email address
Customer ID A unique identifier for this customer — typically the customer ID from your billing system. Required

1. Should be unique

2. Can have alphanumeric and special characters

3. Should be greater than 0 and less than 255 characters

Lead created at Date when the lead was created. We use this information to generate lead volume reports. Not required Choose the date from the drop-down or enter it manually in the YYYY-MM-DD format
Free trial started at Date when the free trial started. We use this information to generate reports of your free trials and trial-to-paid conversions. Not required Choose the date from the drop-down or enter it manually in the YYYY-MM-DD format
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.

4. Add a plan

To create a new subscription plan, navigate to Plans > NEW PLAN.

Enter a Name, a unique Plan ID, Interval Count and Interval Unit. Once complete, click the green checkmark to save.

ChartMogul only accepts day, month, or year as valid interval units for a plan. The interval count should be a positive integer greater than zero. To understand interval unit and interval count, here are some examples:

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

Once the plan details are submitted successfully, a plan UUID is automatically generated.

5. Add an invoice

Invoices with at least one corresponding invoice line item are used to generate subscriptions, transactions, refunds, and MRR movements in ChartMogul.

To create a new invoice, navigate Invoices > NEW INVOICE. Add the invoice details in the new row and once complete, click the green checkmark to save.

Immediately after creating a new invoice, an error will appear in the line items column and the import status will be Failed. This will update to Processed after invoice line items are successfully added to this invoice. Learn more.Screenshot_2021-06-16_at_12.54.34.png
The fields in the invoices table and their supported values are summarized in the table below.
Column Name Description Field Type Value
Customer Customer name for whom we want to add an invoice Required Choose the customer name from the drop-down
Invoice ID A unique identifier for the invoice. This is typically the invoice number in your billing system Required

1. Should be unique

2. Can have alphanumeric and special characters

3. Should be greater than 0 and less than 255 characters

Invoice date Date on which the invoice was raised Required Choose the invoice date from the drop-down or enter it manually in the YYYY-MM-DD format

Due date

Date within which the invoice needs to be paid Not Required Choose the due date from the drop-down or enter it manually in the YYYY-MM-DD format
Currency 3 letter ISO code of the currency in which the invoice is billed Required

Choose the currency from the drop-down

6. Add invoice line items

Invoice line items and their corresponding invoices are used to generate subscriptions and MRR movements in ChartMogul. For an invoice to be processed properly it must have at least one line item.

To add a new invoice line item to an existing invoice, navigate to Invoice Line Items > NEW INVOICE LINE ITEM. Add the invoice line item data in the new row and once complete, click the green checkmark to save.

Learn more about how invoice line items impact ChartMogul.

The fields in the invoice line items table and their supported values are summarized in the table below.

Column name Description Field type Value
Invoice ID A unique identifier for the invoice. This is typically the invoice number in your billing system Required Choose the invoice id from the drop-down
Subscription ID A unique identifier for the subscription. This is typically the subscription ID in your billing system Required

1. Should be unique for this data source

2. Can have alphanumeric and special characters

3. Should be greater than zero and less than 255 characters

Type Choose if it is a one time or a subscription Required Choose the type from the drop-down
Service period start Date on which the subscription starts Required for subscriptions Choose the due date from the drop-down or enter it manually in the YYYY-MM-DD format
Service period end Date on which the subscription ends Required for subscriptions Choose the due date from the drop-down or enter it manually in the YYYY-MM-DD format
Prorated Select if it is a prorated subscription or not Not required Choose yes or no from the drop-down
Amount The final amount charged towards the invoice line item Required Should be a number and can have up to two decimal places
Transaction fees Amount paid to your billing system and/or payment processor for this particular invoice line item Not required Should be a number and can have up to two decimal places
Plan Plan for this subscription Required for subscriptions Choose the plan from the drop-down
Quantity Quantity of the invoice for this line item Not required Should be a non-zero integer
Discount amount The amount discounted when a discount is applied to this invoice line item Not required Should be a number and can have up to two decimal places
Tax amount Tax amount is the amount of tax applied to this invoice line item Not required Should be a number and can have up to two decimal places

7. Add transactions

Transactions represent the payment or refund attempts related to an invoice. Transactions do not impact subscription analytics or MRR movements, but they do determine cash flow metrics and revenue recognition schedules.

To create a new transaction, navigate to Transactions > NEW TRANSACTION. Add the transaction details in the new row and click the green check mark to save. Include failed transaction attempts to report on Failed Transactions.

8. Add 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

1. Should be unique for this data source

2. Can have alphanumeric and special characters

3. Should be greater than zero and less than 255 characters

Subscription Set ID Identifier for subscriptions with multiple components. Not required

1. Should be unique for this data source

2. Can have alphanumeric and special characters

3. Should be greater than zero and less than 255 characters

Event ID A unique identifier for the event, typically provided by your billing system. Not required

1. Should be unique for this data source

2. Can have alphanumeric and special characters

3. Should be greater than zero and less than 255 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. Required when the subscription event type is Retracted

1. Should be unique for this data source

2. Can have alphanumeric and special characters

3. Should be greater than zero and less than 255 characters

Event Date The date the subscription change was requested or triggered. Required

Choose the date from the drop-down or enter it manually in the YYYY-MM-DD format

Effective Date The date the subscription change will be implemented. Required

Choose the date from the drop-down or enter it manually in the YYYY-MM-DD format

Plan A unique identifier for this plan, typically provided by your billing system. Required

Choose the plan from the drop-down

Currency 3 letter ISO code of the invoice’s currency Required

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

Should be a number and can have up to two decimal places

Tax Amount Tax applied to a subscription event. Defaults to zero. If specified, tax is excluded from CMRR. Not required

Should be a number and can have 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. Not required

Should be a non-zero integer

9. View 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.

10. Understanding how line items and transactions impact different aspects in ChartMogul

Invoice line items are the key component of how ChartMogul processes recurring and non-recurring billing information and calculates MRR:

  • Amount — The amount billed for a subscription is the primary component used to calculate MRR.
  • Plans — With monthly plans, MRR is simply the subscription price paid each month. If customers are paying for plans in longer billing intervals (e.g. one year) ChartMogul simply divides the amount paid for the subscription by the number of months in the subscription period.
  • Discounts — ChartMogul assumes discounts have already been deducted from the specified Amount value. If Discount Amount is specified, it doesn’t impact MRR, but enables a more detailed analysis.
  • Taxes — Taxes must be excluded from the calculation of MRR. If specified, Tax Amount is used to deduct the tax prior to the calculation of MRR.
  • Quantity — Subscription quantity does not factor into the calculation of MRR. If specified, quantity is used to generate the Subscription Quantity and Quantity Churn Rate charts.
  • Prorated — Prorated items in invoices must be explicitly identified for ChartMogul to calculate their contribution to MRR correctly. If specified as Yes the Prorated attribute impacts the calculation of MRR. Learn more about adding pro-rated invoices.
  • Transaction Fees — Transaction fees are not deducted from MRR.
  • One-time payments are excluded from MRR.

Below are some basic scenarios and how to define line items for each of them. Learn more about advanced scenarios and how to add them.

Scenario 1: Subscribe a customer to a plan — Monthly

  • Your customer Wayne Enterprises buys a license of your monthly bronze plan for the month of October starting from October 1st, 2018
  • Your monthly bronze plan is $100
  • In this case, MRR = $100

Add these details as an invoice line item:

Line Item Value
Invoice JL_FG_13400001 (Wayne Enterprises)
Subscription ID jl_subid_01
Type Subscription
Prorated No
Service period start 2018-10-01
Service period end 2018-11-01
Amount $100
Plan JL Bronze Plan Monthly (jlbronzemonthly)
Quantity 1

Scenario 2: Subscribe a customer to a plan — Annual

  • Your customer Daily Metropolis buys an annual bronze plan starting from Dec 1st, 2018
  • Your annual bronze plan is $1050 that includes a tax of $50
  • You have also provided a discount of $200 on the total purchase amount
  • The transaction fee is $40
  • MRR = [Amount charged — Tax amount] / Plan duration in months
  • In this case MRR = [$850 — $50]/ 12 = $66.67

Add these details as an invoice line item:

Line Item Value
Invoice JL_FG_13400002 (Daily Metropolis)
Subscription ID jl_subid_02
Type Subscription
Prorated No
Service period start 2018-12-01
Service period end 2019-12-01
Amount $850
Transaction fees $40
Plan JL Bronze Plan Annual (jlbronzeannual)
Quantity 1
Discount amount $200
Tax amount $50

Scenario 3: Renew an existing subscription

Ensure that the Subscription ID does not change during a renewal.
  • Your customer Wayne Enterprises is currently on a monthly bronze plan with a charge of $100 per month for the month of October, starting 1st of October, 2018
  • At the start of the new month 1st of November, the customer has renewed their existing subscription
  • In this case, MRR will remain $100

Ddd these details as an invoice line item:

Line Item Value
Invoice JL_FG_13400004 (Wayne Enterprises)
Subscription ID jl_subid_01
Type Subscription
Prorated No
Service period start 2018-11-01
Service period end 2018-12-01
Amount $100
Plan JL Bronze Plan Monthly (jlbronzemonthly)
Quantity 1

11. Edit existing data

Data can be edited directly in the tables in the data source. Click   to edit data and click the green checkmark to submit your changes.

Some fields, such as the Customer ID, are permanent and cannot be changed.

Was this article helpful?