You'll need to be an Admin or Owner in ChartMogul and an Admin in Recurly to complete the steps in this article.
Recurly is one of ChartMogul’s billing system integrations, allowing you to import customer, subscription, and transaction data to generate subscription analytics and cash flow metrics. Read our launch announcement.
Learn more about getting started with importing data for Subscription Analytics.
Here’s what we cover in this article:
- Overview
- Data Settings
- Before you begin
- Connecting Recurly to ChartMogul
- Using CMRR with Recurly
- Manually re-syncing data
- Deleting Recurly as a source
Overview
The following table provides details on key aspects of how ChartMogul integrates with Recurly.
| Customer import event |
If you’re using the latest version of our Recurly integration, ChartMogul imports customers when they are created in Recurly. If you’re using a previous version, ChartMogul imports customers when they start a trial or have an invoice in Recurly. |
|---|---|
| Leads | ChartMogul imports lead dates when customers start a free trial in Recurly. The lead date is the same as the free trial start date. |
| Free trials | ChartMogul imports free trial start dates. |
| Contacts | ChartMogul does not import contacts from Recurly. Learn more about adding contacts. |
| Custom attributes | ChartMogul does not import custom attributes from Recurly. It is, however, possible for you to create and populate custom attributes manually. Learn more. |
| Historical data | When you add Recurly as a source, ChartMogul imports all existing subscription billing data. |
| Credits | ChartMogul imports credits and reports them in the Balance row of Net Cash Flow and Gross Cash Flow. |
| Paused subscriptions | ChartMogul does not offer native support for paused subscriptions. When a subscription is paused in Recurly, the subscription is canceled in ChartMogul at the end of its current service period, and a new subscription is created once it resumes. |
| Reviewing subscription data in-app |
If you’re using the latest version of our Recurly integration, 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 Settings & Data > 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. These data tables are, unfortunately, currently not available for previous versions of our Recurly integration. |
| Tax handling | Taxes configured in Recurly are listed 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 | Supported. Learn more. |
| Voided transactions |
If you’re using the latest version of our Recurly integration, voided transactions are now imported as voided invoices and we no longer include this in your Net Cash Flow and Gross Cash Flow reports. If you’re using a previous version, ChartMogul classifies voided invoices as voided transactions and reports them in Net Cash Flow and Gross Cash Flow reports. |
| 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 | Fully supported. 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 Recurly and, as a result, transaction fees are automatically excluded from Monthly Recurring Revenue (MRR). |
| Open invoice support | Fully supported. Learn more. |
Integration versioning
On January 11, 2024, we released a new version of our Recurly integration. Read our launch announcement.
To check if you’re using the latest version, navigate to Settings & Data > Sources and select your Recurly source. If you see a series of tables with customer and invoice data, you’re using the latest version of our Recurly integration. If you’re only able to view the setup modal, you’re using a previous version, and some features may be unavailable.
To migrate your account to the latest version of our Recurly integration, contact support.
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 connecting Recurly to ChartMogul will require you to manually re-sync data.
- Log in to the Recurly account you’d like to connect to ChartMogul. If you have multiple Recurly accounts, you’ll need to add each account as a separate source in ChartMogul.
- Locate your Recurly subdomain. For example, if your Recurly URL is
mycompany.recurly.comthen your Recurly subdomain ismycompany. - Create an API key in Recurly you’d like ChartMogul to use to import historical data. Learn more.
- Decide how you’d like ChartMogul to classify customers with open invoices using the Invoiced Customer Handling setting.
Connecting Recurly to ChartMogul
- Navigate to Settings & Data > Sources.
- Click Add Source.
- Make sure that the Subscription data tab is selected and click Recurly.
- Enter a unique name and click Next.
- When Recurly is added as a source, ChartMogul generates a webhook URL for Recurly to use for real-time reporting. Locate it in the Webhook URL field.
- Within Recurly, navigate to Integrations > Webhooks.
- Click Configure, then Configure a new endpoint.
- Give your endpoint a name.
- Paste your Webhook URL into the Endpoint URL field.
- Leave the HTTP Auth Username and HTTP Auth Password fields blank.
- Select XML as the format.
- In the Notifications section, click Select All Notifications.
- Click Save Changes to complete the webhook setup.
- Next, navigate to Integrations > API Credentials. There, you'll find your API keys. Reveal and copy the Private API Key so ChartMogul can import historical data.
- Within ChartMogul, paste the key into the Private API key field.
- Now, paste your Recurly subdomain (the
mycompanypart ofmycompany.recurly.com) into the Recurly subdomain field. - Click Save.
- Configure the Invoiced customer handling setting.
- Finally, click Import Data to connect Recurly 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 Recurly.
ChartMogul automatically imports all data once you’ve successfully connected it to Recurly. No further action is needed to import historical data.
Using CMRR with Recurly
Committed Monthly Recurring Revenue (CMRR) is a projection of MRR into the future. It’s calculated using subscription events, which Recurly imports automatically. Learn more about CMRR.
Here’s what you need to know about using CMRR with Recurly:
| Detail | Impact |
|---|---|
| ChartMogul begins importing subscription events on the date Recurly is added as a source. | Historical subscription events are not imported. |
Recurly does not support the Start (Scheduled) event type. |
New Business and Reactivation are not reported in the Committed MRR Forecast. |
| If you’re using a previous version of our Recurly integration, data tables aren't available. | Subscription events are not visible in ChartMogul when using a previous version of the Recurly integration. |
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 Recurly source will not cause any changes you’ve subsequently made to customers and their subscriptions inside ChartMogul — such as lead and trial data, manually edited MRR, merged customers, edited customer details, or connected subscriptions — to be lost.
Here’s how to manually re-sync data when needed:
- Within ChartMogul, navigate to Settings & Data > Sources.
- Find your Recurly 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 Recurly as a source
Deleting a source is permanent and cannot be undone.
Before deleting a source, please note the following:
- 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 Recurly source, navigate to Settings & Data > 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.