Recurly Integration Guide

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 supported billing systems, allowing you to import customer, subscription, and transaction data to generate subscription analytics and cash flow metrics. Read our launch announcement.

Learn more about other import methods in Getting started with importing data.

Here’s what we cover in this article:

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 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.

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.

To check if you’re using the latest version, navigate to Data & Config > 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.com then your Recurly subdomain is mycompany.
  • 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

  1. Navigate to Data & Config > Sources.
  2. Click Add Source.
  3. Select Recurly.
  4. Enter a unique name and click Next.
  5. 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.
  6. Within Recurly, navigate to Integrations > Webhooks.
  7. Click Configure, then Configure a new endpoint.
  8. Give your endpoint a name.
  9. Paste your Webhook URL into the Endpoint URL field.
  10. Leave the HTTP Auth Username and HTTP Auth Password fields blank.
  11. Select XML as the format.
  12. In the Notifications section, click Select All Notifications.
  13. Click Save Changes to complete the webhook setup.
  14. 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.
  15. Within ChartMogul, paste the key into the Private API key field.
  16. Now, paste your Recurly subdomain (the mycompany part of mycompany.recurly.com) into the Recurly subdomain field.
  17. Click Save.
  18. Configure the Invoiced customer handling setting.
  19. 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:

  1. Within ChartMogul, navigate to Data & Config > Sources.
  2. Find your Recurly 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 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 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!