Recurly Integration

Recurly is a subscription management platform that provides flexible billing, revenue optimization, and churn reduction tools. LostChurn connects to Recurly via API key and processes webhook notifications to orchestrate failed payment recovery beyond Recurly's built-in dunning.

Prerequisites

• An active Recurly account (Core, Professional, or Elite plan)
• Access to the Recurly Dashboard with admin permissions
• A Recurly API key with appropriate permissions
• A LostChurn account with at least one workspace created

Connection Steps

1. In the Recurly Dashboard, navigate to Integrations > API Credentials.
2. Under Private API Keys, click Add Private API Key.
3. Name the key LostChurn and set the following scopes:
   • Accounts: Read
   • Subscriptions: Read and Write
   • Invoices: Read and Write
   • Transactions: Read
   • Plans: Read
4. Click Create and copy the generated API key.
5. In your LostChurn dashboard, go to Settings > Integrations and click Connect Recurly.
6. Enter your Recurly subdomain (the subdomain portion of your-site.recurly.com) and paste the API key.
7. Click Save and Verify. LostChurn makes a test API call to confirm the credentials are valid and the subdomain is correct.

Webhook Configuration

1. In the Recurly Dashboard, go to Integrations > Webhooks.
2. Click Configure or Add New Endpoint.
3. Set the endpoint URL to:

   https://webhooks.lostchurn.com/v1/recurly

4. Select the following webhook event notifications:
   • Payment Notifications:
     • failed_payment_notification
     • successful_payment_notification
     • void_payment_notification
   • Subscription Notifications:
     • new_subscription_notification
     • updated_subscription_notification
     • canceled_subscription_notification
     • expired_subscription_notification
     • renewed_subscription_notification
     • reactivated_account_notification
   • Invoice Notifications:
     • new_invoice_notification
     • past_due_invoice_notification
     • closed_invoice_notification
   • Dunning Notifications:
     • new_dunning_event_notification
   • Billing Info Notifications:
     • updated_billing_info_notification
     • billing_info_update_failed_notification
5. Click Save.

Webhook Authentication

Recurly secures webhook delivery using HTTP Basic Authentication. When configuring the webhook endpoint in Recurly, you set a username and password that Recurly includes in the Authorization header of every webhook request.

LostChurn verifies these credentials on every incoming webhook using a timing-safe comparison. To configure this:

1. In the Recurly Dashboard, set a username and password for the LostChurn webhook endpoint.
2. In your LostChurn dashboard, go to Settings > Integrations > Recurly and enter the same Webhook Username and Webhook Password.

Without matching credentials, all webhook deliveries from Recurly will be rejected with a 401 response.

Verify Connection

1. In the Recurly Dashboard, go to Integrations > Webhooks and select the LostChurn endpoint.
2. Recurly does not have a built-in "send test" button, so you need to trigger a real event. Create a test subscription in your Recurly sandbox site using one of Recurly's test card numbers:
   • Use card number 4000000000000341 to simulate a declined transaction after initial authorization.
3. In your LostChurn dashboard, navigate to Events and confirm that the failed payment event appears.

A successful connection shows a green Connected badge on the Recurly card in Settings > Integrations.

Supported Events

Provider-Specific Notes

Recurly's Built-In Dunning

Recurly includes its own dunning management feature. When using LostChurn alongside Recurly's native dunning, you have two options:

1. Disable Recurly's dunning emails and let LostChurn handle all customer communications. This gives you full control over messaging, timing, and personalization. To disable Recurly's dunning emails, go to Configuration > Dunning Management in the Recurly Dashboard and uncheck Send dunning emails.
2. Run both in parallel with LostChurn handling supplementary recovery actions (such as SMS, in-app messages, or AI-optimized email timing) that complement Recurly's built-in emails. If you choose this approach, configure LostChurn to skip email dunning to avoid sending duplicate messages.

Sandbox Sites

Recurly provides sandbox sites for testing. Your sandbox site has a separate subdomain (typically ending in -test or -sandbox). You can connect both your sandbox and production sites to LostChurn simultaneously. Sandbox events are labeled accordingly in the Events feed.

XML Webhook Format

Unlike most modern payment processors that use JSON webhooks, Recurly sends webhook notifications as XML. LostChurn automatically parses and normalizes Recurly's XML payloads into its internal unified event format. No additional configuration is needed.

API Version

LostChurn uses Recurly API v3 (REST). Ensure your Recurly site is configured to support API v3. Older API versions (v2) are not supported.

Revenue Recognition

Recurly provides revenue recognition data with invoices. LostChurn captures this metadata so that recovered revenue is correctly attributed in your accounting reports. Deferred revenue and recognized revenue from recovered payments are tracked separately.

Rate Limits

Recurly enforces rate limits of 2,000 requests per hour for most API endpoints. LostChurn batches operations and distributes retry attempts across the hour to stay within this limit. The current rate limit usage is visible in Settings > Integrations > Recurly > API Usage.