If you're new to ChartMogul, learn how we import subscription data to generate metrics.
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
- Data Settings
- How this integration works
- Before you begin
- Connecting Chargebee to ChartMogul
- Manually re-syncing data
- Deleting Chargebee is a source
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 | ChartMogul automatically imports metadata from a customer object 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 using our Data Platform | 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 Platform > 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. This new integration is currently in beta. To have it enabled in your account, contact support.
To check if you’re using the latest version, navigate to Data Platform > Sources and locate your Chargebee source. If the Chargebee logo includes a NEW label, you’re using the latest version. If the logo does not include a NEW label, you’re using the previous version, and some features may be unavailable.
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.comthen your Chargebee subdomain ismycompany. - 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.
- Log in to your Chargebee account, navigate to Settings > Configure Chargebee > API keys.
- Click + Add API Key.
- Select Read-Only Key.
- Grant the key All permissions.
- Name the key, e.g., ChartMogul Read-only.
- 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:
- Within ChartMogul, navigate to Data Platform > Sources.
- Click ADD A SOURCE.
- Select Chargebee.
- Enter a unique name for your source in the Name field and click Next.
- Paste your Chargebee subdomain into the Chargebee Subdomain field.
- Paste the API key you created in Step 1 into the Chargebee API Key field.
- 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.
- Copy your Webhooks URL.
- Within Chargebee, navigate to Settings > Configure Chargebee > Webhooks.
- Click + Add Webhook.
- Name the webhook, e.g., ChartMogul Webhook.
- Paste your webhook URL into the Webhook URL field.
- Select Version 2 as the API Version.
- Click Create.
After the webhook is added, changes in Chargebee are synced in real-time with ChartMogul.
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 edited customer details, edited MRR, or merged customers.
For information about whether connected subscriptions can be preserved as part of a re-sync, please contact support.
Here’s how to manually re-sync data when needed:
- Within ChartMogul, navigate to Data Platform > Sources.
- Find your Chargebee source and click the Settings icon.
- 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 profile and data from the non-deleted source will remain in ChartMogul.
To delete a Chargebee source, navigate to Data Platform > Sources. Find the source in the list and click the Settings icon. From there, click DELETE THIS SOURCE.
Next Steps
- Learn more about segmentation.
- Customize your Dashboard.
- Download the ChartMogul mobile app.
- Get started with charts.