Chargebee Integration Guide

If you're new to ChartMogul, learn how we import subscription data to generate metrics.

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

Chargebee is one of ChartMogul’s supported billing systems, allowing you to import customer, subscription, and transaction data to generate subscription analytics and cash flow metrics. Read our launch announcement.

Here's what we cover in this article:

Overview

The following table provides details on key aspects of how ChartMogul integrates with Chargebee. 

Customer import event ChartMogul imports customers when they are created in Chargebee.
Leads ChartMogul imports lead dates when a customer is created in Chargebee.
Free trials ChartMogul imports free trial start dates.
Contacts ChartMogul does not import contacts from Chargebee. Learn more about adding contacts.
Custom attributes

In the latest version of our Chargebee integration, ChartMogul imports the following data as custom attributes to customers:

If you’re using a previous version, ChartMogul imports customer metadata as custom attributes.

Historical data When you add Chargebee as a source, ChartMogul imports all existing subscription billing data.
Credits

ChartMogul reports Promotional Credits as a discount.

In the latest version of our Chargebee integration, ChartMogul reports credit notes from subscription changes and invoice refunds as credit to a customer's balance. If you’re using a previous version, ChartMogul reports credit notes from subscription changes or invoice refunds as non-recurring refunds.
Paused subscriptions ChartMogul does not offer native support for paused subscriptions. When a subscription is paused in Chargebee, the customer status in ChartMogul is set to Past due at the end of the current service period, and the subscription continues to contribute to Monthly Recurring Revenue (MRR) while paused.
Reviewing subscription data in-app Once imported, ChartMogul gives you complete visibility into your data as it exists in our platform through a series of data tables. To view these tables, navigate to Data & Config > Sources, then select the source you want to view. Learn more about the data stored in each table and table column or export it to CSV.
Tax handling Chargebee lists taxes separately on invoices. ChartMogul, therefore, excludes taxes from Monthly Recurring Revenue (MRR).
Automated tags ChartMogul does not add any automated tags to customers. Instead, learn how to add tags in-app or using our API.
Subscriptions with multiple components Not currently supported. Learn more.
Voided transactions ChartMogul uses invoice data to calculate metrics and analytics and transaction data to generate cash flow reports. If you’re using a previous version, ChartMogul does not import voided invoices. However, the latest version of our integration imports voided invoices. ChartMogul does not support transactions voided in Chargebee.
Update frequency Real-time. Learn more.
Maintained by This integration is built and maintained by ChartMogul. Contact our support team for assistance.

Data Settings

The following table provides details on how ChartMogul’s data settings work with your billing system.

Smart Activity Classification Fully supported. Learn more.
Handling Past-due Subscriptions Fully supported. Learn more.
Churn Recognition Fully supported. Learn more.
Free Customer Handling Supported for ChartMogul accounts opened after August 17, 2022. Learn more.
Refund Handling ChartMogul does not deduct refunded transactions from Monthly Recurring Revenue (MRR).
Transaction Fee Handling ChartMogul does not import transaction fees from Chargebee and, as a result, transaction fees are automatically excluded from Monthly Recurring Revenue (MRR).
Open invoice support Fully supported for the latest version of our Chargebee integration. Learn more.

How this integration works

Integration versioning

On November 2, 2022 we released a new version of our Chargebee integration. To have it enabled in your account, contact support.

To check if you’re using the latest version, navigate to Data & Config > Sources and locate your Chargebee source.

Chargebee_source_current_logo.png

If the Chargebee logo is the current version, you’re using the latest version of the integration. If the logo is the previous version, you’re using the previous version of the integration, and some features may be unavailable.

Chargebee_logo_versions.png

There are also several additional details you should understand and consider when using Chargebee with ChartMogul.

Detail Impact
If your Chargebee account was migrated from Product Catalog 1.0 to Product Catalog 2.0, or if you’re using a previous version of our integration, you must contact Chargebee support to enable plans and add-ons endpoints.

ChartMogul requires these endpoints to accurately import historical data. Otherwise, historical data may not be accurately reported.

Chargebee only provides cancellation dates for the most recent 90 days.

During the initial import, ChartMogul can only import cancellation dates for customers who canceled their subscription at some point in the previous 90 days. Customers who cancel and reactivate a subscription in the previous 90 days may be reported differently in ChartMogul than Chargebee, depending on the date Chargebee is added as a source.

For example, a customer cancels their subscription on January 5 and reactivates it on February 5. If Chargebee is added as a source on (or before) April 5, ChartMogul imports the cancellation and reactivation dates. However, if Chargebee is added as a source on April 6 (91 days after the cancellation), ChartMogul is only able to import the reactivation date. Therefore, ChartMogul reports the subscription as active from January 5 to February 5.

ChartMogul doesn't support subscriptions which include a plan and add-on with different service periods. ChartMogul is unable to accurately report Monthly Recurring Revenue (MRR).
To immediately apply prorated changes to a subscription, select the Apply prorated credits and charges option in Chargebee. If this option is not selected, mid-billing period prorated add-ons are applied at the start of the next billing period.
ChartMogul doesn't support advanced billing for subscriptions with add-ons. ChartMogul imports invoices on the issue date and starts subscriptions on the service period start date.
ChartMogul does not support Chargebee’s Calendar Billing feature. ChartMogul is unable to accurately report Monthly Recurring Revenue (MRR) when Calendar Billing is enabled.
If you’re using a previous version, ChartMogul is unable to report partial invoice payments, and instead, reports each payment as the total value of the invoice. (However, ChartMogul reports partial refunds accurately.) ChartMogul is unable to accurately report partial payments in cash flow reports.
If you’re using a previous version, ChartMogul combines plans and add-ons into a single invoice line item. Plan and add-on details (including billing and tax amounts) are not visible in a customer’s subscriptions or transactions. There is no visibility into the amount each component (plan vs. add-on) contributes to Monthly Recurring Revenue (MRR).
If you’re using a previous version, prorated changes to add-ons are reported as changes in subscription quantity. ChartMogul is unable to accurately report Subscription Quantity.
If you’re using a previous version, plan switches in Chargebee generate a credit note which reduces MRR to $0. ChartMogul reports this change as a void movement followed by contraction.

Before you begin

  • Review your data settings to ensure ChartMogul calculates metrics and analytics based on the needs of your business. Adjusting these settings after importing data will require you to manually re-sync data.
  • Log in to the Chargebee account you’d like to connect to ChartMogul. If you have multiple Chargebee accounts, you’ll need to add each account as a separate source in ChartMogul.
  • Locate your Chargebee subdomain. For example, if your Chargebee URL is mycompany.chargebee.com then your Chargebee subdomain is mycompany.
  • Ensure Hide Zero Value Line Items is disabled in Chargebee. ChartMogul requires Chargebee to generate a $0 invoice to accurately report paid to free plan switches as contraction.

Connecting Chargebee to ChartMogul

Step 1 — Create a read-only API key

ChartMogul uses API keys to connect to Chargebee. For added security, we recommend creating a read-only API key in Chargebee to grant ChartMogul access to your Chargebee account. Learn more.

  1. Log in to your Chargebee account, navigate to Settings > Configure Chargebee > API keys.
  2. Click + Add API Key.
  3. Select Read-Only Key.
  4. Grant the key All permissions.
  5. Name the key, e.g., ChartMogul Read-only.
  6. Click Create Key.

Note your API Key. You'll need this in Step 2 when adding Chargebee as a source in ChartMogul.

Step 2 — Add Chargebee as a source

Next, add Chargebee as a source in ChartMogul:

  1. Within ChartMogul, navigate to Data & Config > Sources.
  2. Click Add Source.
  3. Select Chargebee.
  4. Enter a unique name for your source in the Name field and click Next.
  5. Paste your Chargebee subdomain (the mycompany part of mycompany.chargebee.com) into the Chargebee Subdomain field.
  6. Paste the API key you created in Step 1 into the Chargebee API Key field.
  7. Finally, click Import Data to connect Chargebee to ChartMogul and start importing your data.

The import can take some time, depending on the number of customers. After the import has concluded, ChartMogul will update automatically with any new activity from Chargebee.

ChartMogul automatically imports all data once you’ve successfully connected it to Chargebee. No further action is needed to import historical data.

Step 3 — Add a webhook in Chargebee to keep your data synced

Once you’ve imported data, ChartMogul generates a webhook that you’ll need to add to Chargebee to keep your data synced in real-time.

  1. Copy your Webhooks URL.
  2. Within Chargebee, navigate to Settings > Configure Chargebee > Webhooks.
  3. Click + Add Webhook.
  4. Name the webhook, e.g., ChartMogul Webhook.
  5. Paste your webhook URL into the Webhook URL field.
  6. Select Version 2 as the API Version.
  7. Click Create.

After the webhook is added, changes in Chargebee are synced in real-time with ChartMogul.

Using CMRR with Chargebee

Committed Monthly Recurring Revenue (CMRR) is a projection of MRR into the future. It’s calculated using subscription events, which Chargebee imports automatically. Learn more about CMRR.

Here’s what you need to know about using CMRR with Chargebee:

Detail Impact
CMRR is only available with the latest version of our Chargebee integration. If you’re using the previous version of our Chargebee integration, subscription events are unavailable, and you will be unable to view CMRR.
ChartMogul begins importing subscription events on the date Chargebee is added as a source. Historical subscription events are not supported.

Manually re-syncing data

If you alter one of the settings in your source or a data setting requiring a re-sync, you will need to re-import your data to make the behavior consistent historically and going forward.

Re-syncing your Chargebee source will not impact changes you’ve made in ChartMogul such as lead and trial data, edited customer details, edited MRR, or merged customers.

If you’re using the latest version of our Chargebee integration, connected subscriptions will be preserved after a re-sync. If you’re using a previous version, re-syncing data will remove subscription connections.

Here’s how to manually re-sync data when needed:

  1. Within ChartMogul, navigate to Data & Config > Sources.
  2. Find your Chargebee source and click the Settings  icon.
  3. Click Re-Sync Data.

ChartMogul will start re-importing your data and let you know where it’s at with a progress bar.

Deleting Chargebee as a source

Deleting a source is permanent and cannot be undone

Before deleting a source, please note the following:

  • The Chargebee API does not support unsubscribing from webhooks. If you cancel ChartMogul, the ChartMogul webhook URL must be manually removed in Chargebee.
  • All data from this source will be immediately and irrevocably removed from ChartMogul.
  • All MRR adjustments and connected subscriptions will be lost.
  • If this source contains a merged customer, the customer record and data from the non-deleted source will remain in ChartMogul.

To delete a Chargebee source, navigate to Data & Config > Sources. Find the source in the list and click the Settings  icon. From there, click Delete This Source.

Next Steps

Was this article helpful?

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


Thanks for your feedback!