Adding subscription data in ChartMogul

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 in ChartMogul. In this article, we explain how to add data manually through the ChartMogul interface.

You’ll need to add each method you use to bill customers as a source. Let’s say most of your customers pay for their subscriptions with Stripe but a handful use direct debit. In this case, you’ll create two sources: one Stripe source and one custom source. ChartMogul imports subscription data (invoices, invoice line items, transactions, etc.) automatically from Stripe. For your direct debit customers, you’ll need to add this data manually to the custom source. Add this data using the tables outlined in this article, or as manual subscriptions.

Before you begin

Getting started

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

  1. Navigate to Data & Config > Sources and click Add Source.
  2. Select Custom Source.
  3. Enter a unique name.
  4. Click Next.

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

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 > Add Lead/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.

Screenshot of the Invoices table with one newly created invoice. The Line Items and Import Status fields show errors.

Open (unpaid) invoices contribute to your recurring revenue. Don’t add open invoices if you don’t want them included in your MRR.

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.

Status The invoice status based on the invoice’s transactions or user selection. Optional Choose open, written_off, or voided from the drop-down. If you leave this field blank, ChartMogul will classify the invoice as open, paid, or refunded based on its transactions.
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 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 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 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 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 Started, Start (Scheduled), Updated, and Updated (Scheduled) event types.

Choose the plan from the drop-down.

Currency The three-letter ISO code of the invoice’s currency. Required for Started, Start (Scheduled), Updated, and Updated (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 Started, Start (Scheduled), Updated, and Updated (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 Started, Start (Scheduled), Updated, and Updated (Scheduled) event types.

Should be a non-zero integer.

Manual Subscriptions

Add a new manual subscription by navigating to Manual Subscriptions > New Manual Subscription Event.

Column Name Description Field Type Value
Customer Customer associated with the manual subscription Required Choose the customer from the drop-down.
Event Type The change in a subscription is classified as an event type. Required Choose the event type from the drop-down.
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.
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 when the event type is Started or Updated Choose the plan from the drop-down.
Currency The three-letter ISO code of the invoice’s currency. Required when the event type is Started or Updated 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 when the event type is Started or Updated Accepts numbers with up to two decimal places.
Quantity Quantity of manual subscription events being billed. Can be any non-zero integer. Defaults to one. Optional Should be a non-zero integer. If not set, defaults to 1.
Report Cash Flow An option for ChartMogul to automatically generate a transaction to report the MRR amount in cash flow reports. This does not impact your billing system. Optional Choose No or Yes from the drop-down. If not set, defaults to No.

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.
Screenshot of the Subscriptions table with the Cancel Subscription option highlighted.

Was this article helpful?

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


Thanks for your feedback!