LostChurn Docs

Connect Zuora to LostChurn for automatic failed payment recovery on enterprise subscriptions.

The Zuora integration is live. Connect your Zuora account in your LostChurn dashboard under Settings > Integrations.

Zuora is an enterprise subscription billing platform that manages the full subscription lifecycle including billing schedules, payment processing, revenue recognition, and usage metering. LostChurn connects to Zuora via REST API and webhooks to add Smart Retry Engine and dunning capabilities on top of Zuora's native payment retry features.

Prerequisites

An active Zuora account (any edition)
Admin access to your Zuora tenant
A Zuora OAuth client (created during setup)
A LostChurn account with at least one workspace created

Connection Steps

In your LostChurn dashboard, go to Settings > Integrations and click Connect Zuora.
Enter your Zuora Tenant URL (e.g., rest.zuora.com for production or rest.apisandbox.zuora.com for sandbox).
In your Zuora tenant, navigate to Settings > Administration > Manage Users > OAuth Clients.
Click Create OAuth Client with the following settings:
- Name: LostChurn
- Grant Type: client_credentials
Copy the Client ID and Client Secret.
Paste them into the LostChurn connection form and click Save and Verify.

LostChurn uses the following API permissions:

Permission	Purpose
Subscriptions	Read subscription details, status, and renewal dates
Invoices	Read and update invoice status, trigger payment collection
Payments	Read payment history, create payment retries
Payment Methods	Read stored payment methods for retry routing
Accounts	Read account details for dunning communications

Webhook Configuration

After connecting, configure Zuora to send event notifications to LostChurn:

In your Zuora tenant, navigate to Settings > Notifications > Callout Notifications.
Create a new callout notification for each of the following events:

Zuora Event	Endpoint
`Payment Failed`	`https://webhooks.lostchurn.com/v1/zuora`
`Invoice Posted`	`https://webhooks.lostchurn.com/v1/zuora`
`Subscription Cancelled`	`https://webhooks.lostchurn.com/v1/zuora`
`Payment Method Updated`	`https://webhooks.lostchurn.com/v1/zuora`

Set the Authentication Type to Custom and enter the webhook signing secret from your LostChurn integration settings.
LostChurn verifies the x-zuora-signature HMAC-SHA256 header on every incoming request.

Supported Events

Zuora Event	LostChurn Action
Payment failed	Creates a failed payment record, triggers retry evaluation
Invoice posted with balance	Records pending invoice, monitors for payment
Subscription cancelled	Records churn event, triggers reactivation campaign if configured
Payment method updated	Triggers immediate retry of pending failures on updated method
Payment succeeded	Marks recovery as successful, stops active dunning

How Recovery Works

Detection: When a Zuora payment fails, the callout notification sends the event to LostChurn in real time.
Analysis: LostChurn analyzes the gateway decline code from the payment record and determines the optimal recovery strategy.
Smart Retry: LostChurn schedules retries at optimal times via the Zuora Payments API. The retry creates a new payment against the outstanding invoice.
Dunning: In parallel, LostChurn sends personalized recovery emails and optional SMS messages to the account contact with a payment update link.
Resolution: When the payment succeeds (either via retry or customer action), Zuora fires a success event and LostChurn marks the recovery as complete.

If you use Zuora's built-in payment retry rules (under Settings > Billing > Payment Retry Rules), consider disabling them to avoid conflicts with LostChurn's Smart Retry Engine. Alternatively, configure LostChurn to work alongside Zuora's retry schedule by setting LostChurn to "monitor only" mode for the initial retry window.

Zuora-Specific Features

Amendment API Integration

LostChurn reads Zuora amendments to understand subscription changes that may affect recovery strategy. For example, if a subscription was recently downgraded, LostChurn adjusts the recovery messaging accordingly.

Revenue Recognition

LostChurn tags recovered payments in Zuora with the original invoice date, ensuring revenue recognition schedules remain accurate in Zuora Revenue.

Multi-Entity Support

Zuora supports multi-entity configurations for organizations with multiple business units. LostChurn connects to each entity separately through entity-scoped OAuth credentials. Events are tagged with the originating entity for filtering in analytics.

Usage-Based Subscriptions

For usage-based billing in Zuora, LostChurn factors in usage patterns when scheduling retries. High-usage customers receive more aggressive recovery to prevent service disruption.

Verify Connection

In your LostChurn dashboard, navigate to Settings > Integrations.
The Zuora card should show a green Connected badge and your tenant URL.
Click Send Test Event to verify the webhook path. LostChurn sends a test callout and confirms receipt.
To test end-to-end, create a test subscription in your Zuora sandbox and trigger a payment failure using a test payment method.

Provider-Specific Notes

Sandbox Testing

Zuora provides sandbox environments (apisandbox.zuora.com) for development and testing. LostChurn fully supports sandbox connections and labels events as test data. Always test the full recovery flow in sandbox before enabling in production.

API Rate Limits

Zuora enforces API rate limits based on your edition:

Standard: 40 concurrent requests, 1500 requests per minute
Enterprise: Higher limits based on contract

LostChurn monitors the RateLimit-Remaining header and throttles requests accordingly. For high-volume tenants, LostChurn batches operations and schedules retries during off-peak hours.

Gateway Configuration

Zuora supports multiple payment gateways per tenant. LostChurn reads the gateway configuration from each payment to extract gateway-specific decline codes and route retries through the appropriate gateway.

Zuora Integration