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.

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 ChartMogul imports customers when they start a free trial or once their first payment is processed 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.
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 Credit 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 using our Data Platform For select billing systems, ChartMogul gives complete visibility into your data as it exists in our platform through a series of data tables. These data tables are, unfortunately, currently not available for Recurly.
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 ChartMogul imports voided transactions in Recurly.
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.
Auto-churn of Delinquent 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.

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 Platform > Sources.
  2. Click ADD A 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 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.
Data tables aren't available. Subscription events are not visible in Data Platform.

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 manually editing MRR, merging customers, editing customer details, or connecting subscriptions — to be lost.

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

  1. Within ChartMogul, navigate to Data Platform > 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 andconnected 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 Recurly 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

Was this article helpful?

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


Thanks for your feedback!