Understanding invoice line items in ChartMogul – Help Center

Invoice line items play a key role in how ChartMogul processes recurring and non-recurring billing information and calculates MRR.

In this article, we explain how different invoice line item attributes impact your metrics in ChartMogul, as well as common scenarios for adding invoice line items to a custom data source using the app interface.

Here’s what we cover in this article:

Understanding invoice line item attributes
Basic scenarios
Advanced scenarios

Before you begin

Learn how to add billing data in-app with Data Platform.

Understanding invoice line item attributes

Here’s how different invoice line item attributes impact the way ChartMogul processes billing information and calculates MRR:

Attribute	Impact
Amount	The amount billed for a subscription is the primary component used to calculate MRR.
Balance Transfer	This attribute specifies whether the line item 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.
Discount Amount	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.
Event Order	This attribute controls the order in which line items are processed. If two line items have the same service period start date, the line item with the Event Order value of “1” is processed before the line item with the Event Order value of “2”. If this attribute is not set, ChartMogul processes the line items in the order they were created.
Plan	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 divides the amount paid for the subscription by the number of months in the subscription period.
Prorated?	You must explicitly identify prorated line items by setting this attribute to Yes. This way ChartMogul can accurately calculate their contribution to MRR. Learn more about adding prorated invoices.
Proration Type	ChartMogul recognizes three proration types: Differential — The Amount and Quantity from this prorated line item are added to the previously calculated MRR and subscription quantity. Full — This prorated line item is treated as a new starting point for the subscription. As such, the Amount and Quantity from this line item are not added to the previously calculated MRR and subscription quantity. Differential MRR — The Amount from this prorated line item behaves like differential proration, which means it is added to the previously calculated MRR. The Quantity from this prorated line item behaves like full proration, which means it is not added to the previously calculated subscription quantity.
Quantity	Subscription quantity does not factor into the calculation of MRR but is used to generate the Subscription Quantity and Quantity Churn Rate charts. If not provided, Quantity defaults to 1.
Tax Amount	Taxes must be excluded from MRR calculation. If specified, Tax Amount is used to deduct the tax before calculating MRR.
Transaction Fees	By default, transaction fees are not deducted from MRR. For custom data sources, you can control this behavior with the Transaction fee handling setting.
Type	Only line items categorized as Subscription contribute to MRR calculation. Non-recurring (one-time) payments are excluded from MRR.

Basic scenarios

This section outlines some basic scenarios that involve adding invoice line items using a custom data source.

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

Subscribing a customer to a monthly plan

Scenario:

Your customer Wayne Enterprises buys a license of your monthly Bronze plan, starting from January 1, 2023.
Your monthly Bronze plan is $100.

Setup:

Add the following details as an invoice line item:

Attribute	Value
Invoice	JL_FG_13400001 (Wayne Enterprises)
Type	Subscription
Amount	$100
Subscription ID	jl_subid_01
Service Period Start	2023-01-01
Service Period End	2023-02-01
Prorated?	No
Plan	JL BronzeMonthly (jlbronzemonthly)

Outcome:

MRR = $100

Screenshot of the Monthly Recurring Revenue chart. At the start of January 2023, MRR increases from 0 to 100 dollars and remains at this level.

Screenshot of the MRR Movements table. It shows a new business movement of 100 dollars described as “Purchased the JL Bronze Monthly plan” on January 1st, 2023. Current MRR after this movement is 100 dollars.

Subscribing a customer to an annual plan

Scenario:

Your customer Daily Metropolis buys an annual Bronze plan starting from December 1, 2023.
Your annual Bronze plan is $1050, which includes a tax of $50.
The customer is offered a discount of $200 on the total purchase amount.
The transaction fee is $40.

Setup:

Add the following details as an invoice line item:

Attribute	Value
Invoice	JL_FG_13400002 (Daily Metropolis)
Type	Subscription
Amount	$850
Subscription ID	jl_subid_02
Service Period Start	2023-03-01
Service Period End	2024-03-01
Prorated?	No
Plan	JL Bronze Annual (jlbronzeannual)
Transaction Fees	$40
Tax Amount	$50
Discount Amount	$200

MRR is calculated using the following formula:

MRR = (Amount charged − Tax amount) / Plan duration in months

Outcome:

MRR = ($850 − $50) / 12 = $66.67

Screenshot of the Monthly Recurring Revenue chart. At the start of January 2023, MRR increases from 0 to 66.67 dollars and remains at this level.

Screenshot of the MRR Movements table. It shows a new business movement of 66.67 dollars described as “Purchased the JL Bronze Annual plan with a 200-dollar discount applied” on March 1st, 2023. Current MRR after this movement is 66.67 dollars.

Renewing an existing subscription

Ensure the Subscription ID does not change during a renewal.

Scenario:

Your customer Wayne Enterprises is currently on a monthly Bronze plan with a charge of $100 per month, starting on January 1, 2023.
At the start of the new month, on February 1, the customer renews their existing subscription.

Setup:

Add the following details as an invoice line item:

Attribute	Value
Invoice	JL_FG_13400004 (Wayne Enterprises)
Type	Subscription
Amount	$100
Subscription ID	jl_subid_01
Service Period Start	2023-02-01
Service Period End	2023-03-01
Prorated?	No
Plan	JL Bronze Monthly (jlbronzemonthly)

Outcome:

MRR remains $100.

Advanced scenarios

This section outlines more advanced scenarios that involve adding invoice line items using a custom data source.

Switching plans (non-prorated)

Scenario:

Your customer Wayne Enterprises is currently on a monthly Bronze plan with a charge of $100 per month, starting from January 1, 2023.
At the start of the new month, on February 1, the customer upgrades to a new monthly Gold plan.
Your monthly Gold plan is $250 per month.

Setup:

Add the following details as an invoice line item:

Attribute	Value
Invoice	JL_FG_13400001 (Wayne Enterprises)
Type	Subscription
Amount	$250
Subscription ID	jl_subid_01
Service Period Start	2023-02-01
Service Period End	2023-03-01
Prorated?	No
Plan	JL Gold Monthly (jlgoldmonthly)

Outcome:

Total MRR = $250
MRR movement = $150

Screenshot of the Monthly Recurring Revenue chart. At the start of January 2023, MRR increases from 0 to 100 dollars. At the start of February 2023, MRR increases to 250 dollars and remains at this level.

Screenshot of the MRR Movements table. It shows a new business movement of 100 dollars is described as “Purchased the JL Bronze Monthly plan” on January 1st, 2023. Current MRR after this movement is 100 dollars. On February 1st, there’s an expansion of 150 dollars described as “Switched plan from JL Bronze Monthly to JL Gold Monthly”. Current MRR after this movement is 250 dollars.

Switching plans (prorated)

Scenario:

Your customer Daily Metropolis is currently on a monthly Bronze plan with a charge of $100 per month.
At the start of the new month, on June 1, 2023, they renew their monthly Bronze plan.
In the middle of the month, on June 16, the customer upgrades to a new monthly Gold plan (prorated upgrade for the remaining 15 days in the billing cycle).
Your monthly Bronze plan is $100 per month, and your monthly Gold plan is $250 per month.
You charge the customer a prorated amount of $125 and credit $50 for the unused time in the Bronze plan.

Setup:

Add the following details as two separate invoice line items:

Invoice line item 1

Attribute	Value
Invoice	JL_FG_13400005 (Daily Metropolis)
Type	Subscription
Amount	−$50
Subscription ID	jl_subid_02
Service Period Start	2023-06-16
Service Period End	2023-07-01
Prorated?	Yes
Plan	JL Bronze Monthly (jlbronzemonthly)

Invoice line item 2

Attribute	Value
Invoice	JL_FG_13400005 (Daily Metropolis)
Type	Subscription
Amount	$125
Subscription ID	jl_subid_02
Service Period Start	2023-06-16
Service Period End	2023-07-01
Prorated?	Yes
Plan	JL Gold Monthly (jlgoldmonthly)
Quantity	1

MRR for prorated line items is calculated using the following formula:

MRR = Amount × Subscription duration ratio × Prorate factor

Learn how ChartMogul calculates the subscription duration ratio and prorate factor.

Outcome:

The amount for this prorated charge is $125, so MRR for the line item = $125 × 1 × 2 = $250.
Since this prorated charge is for a plan change, the new MRR of the subscription is simply the MRR from the new Gold plan ($250).
MRR movement after this charge = $150.

Screenshot of the Monthly Recurring Revenue chart. At the start of May 2023, MRR increases from 0 to 100 dollars. On June 16th, MRR increases to 250 dollars and remains at this level.

Screenshot of the MRR Movements table. It shows a new business movement of 100 dollars is described as “Purchased the JL Bronze Monthly plan” on May 1st, 2023. Current MRR after this movement is 100 dollars. On June 16th, there’s an expansion of 150 dollars described as “Switched plan from JL Bronze Monthly to JL Gold Monthly”. Current MRR after this movement is 250 dollars.

Adding a one-time purchase

Scenario:

Your customer Omega Vision is charged a non-recurring setup fee of $100, which includes a tax of $6.
The transaction fee is $2.

Setup:

Add the following details as an invoice line item:

Attribute	Value
Invoice	JL_FG_13400006 (Omega Vision)
Type	Non-recurring
Amount	$100
Description	Setup fees
Transaction Fees	$2
Tax Amount	$6

Outcome:

MRR is not affected.

Non-recurring invoice line items do not contribute to MRR but they do impact your cash flow metrics.

Adding a refund

Scenario:

Your customer Omega Vision buys a license of your monthly Bronze plan for March, starting from March 1, 2023.
Your monthly Bronze plan is $100.
The customer makes a payment on March 1, 2023.
On March 5, 2023, they realize they no longer need the plan.
As per your refund policy, you issue a full refund on the same day, though the customer can continue to use the services until April 1, 2023.

Setup:

Add the following details as an invoice line item:

Attribute	Value
Invoice	JL_FG_13400007 (Omega Vision)
Type	Subscription
Amount	$100
Subscription ID	jl_subid_03
Service Period Start	2023-03-01
Service Period End	2023-04-01
Prorated?	No
Plan	JL Bronze Monthly (jlbronzemonthly)

Add the following details in the Transactions tab:

Attribute	Value
Invoice	JL_FG_13400019 (Omega Vision)
Type	Refund
Result	Successful
Date	2023-03-05
Transaction ID	trans_id_04

To cancel the customer subscription permanently and churn the customer, go to the Subscriptions tab and cancel the subscription.

Outcome:

After the cancellation, the current MRR is set to zero.

Screenshot of the MRR Movements table. It shows a new business movement of 100 dollars is described as “Purchased the JL Bronze Monthly plan” on March 1st, 2023. Current MRR after this movement is 100 dollars. On March 5th, there’s a churn of minus 100 dollars described as “Cancelled their JL Bronze Monthly plan”. Current MRR after this movement is zero.

Adding a subscription with multiple components

Scenario:

Your customer East Adventure buys a subscription with multiple components (a monthly Bronze plan and a monthly Gold plan), starting from March 1, 2023.
Your monthly Bronze plan is $100.
Your monthly Gold plan is $250.

Setup:

Add the following details as two separate invoice line items:

Invoice line item 1

Attribute	Value
Invoice	JL_FG_13400008 (East Adventure)
Type	Subscription
Amount	$100
Subscription ID	jl_subid_04
Subscription Set ID	jl_subsetid_01
Service Period Start	2023-03-01
Service Period End	2023-04-01
Prorated?	No
Plan	JL Bronze Monthly (jlbronzemonthly)

Invoice line item 2

Attribute	Value
Invoice	JL_FG_13400008 (Barry Allen)
Type	Subscription
Amount	$250
Subscription ID	jl_subid_05
Subscription Set ID	jl_subsetid_01
Service Period Start	2023-03-01
Service Period End	2023-04-01
Prorated?	No
Plan	JL Gold Monthly (jlgoldmonthly)

All invoice line items that are part of a subscription with multiple components should have the same Subscription Set ID. Learn more about subscriptions with multiple components.

Outcome:

Total MRR = $350

Before you begin

Understanding invoice line item attributes

Basic scenarios

Subscribing a customer to a monthly plan

Scenario:

Setup:

Outcome:

Subscribing a customer to an annual plan

Scenario:

Setup:

Outcome:

Renewing an existing subscription

Scenario:

Setup:

Outcome:

Advanced scenarios

Switching plans (non-prorated)

Scenario:

Setup:

Outcome:

Switching plans (prorated)

Scenario:

Setup:

Invoice line item 1

Invoice line item 2

Outcome:

Adding a one-time purchase

Scenario:

Setup:

Outcome:

Adding a refund

Scenario:

Setup:

Outcome:

Adding a subscription with multiple components

Scenario:

Setup:

Invoice line item 1

Invoice line item 2

Outcome:

Related articles