WooCommerce Integration
Connect WooCommerce Subscriptions to LostChurn for automatic failed payment recovery.
The WooCommerce integration is live. Install the LostChurn plugin from your WordPress admin panel or connect via Settings > Integrations in your LostChurn dashboard.
WooCommerce is the leading open-source ecommerce platform for WordPress. Combined with the WooCommerce Subscriptions extension, it enables recurring billing for physical and digital products. LostChurn connects to WooCommerce via a dedicated WordPress plugin that processes subscription lifecycle events and adds Smart Retry Engine and dunning capabilities on top of WooCommerce's existing payment retry logic.
Prerequisites
- WordPress 6.0 or later
- WooCommerce 6.0 or later
- WooCommerce Subscriptions extension (active license)
- PHP 8.0 or later
- A LostChurn account with at least one workspace created
- HTTPS enabled on your WordPress site
Installation
WordPress Plugin
- In your WordPress admin panel, navigate to Plugins > Add New.
- Search for LostChurn in the plugin directory.
- Click Install Now, then Activate.
- Alternatively, download the plugin ZIP from your LostChurn dashboard under Settings > Integrations > WooCommerce and upload it via Plugins > Add New > Upload Plugin.
API Key Setup
- In your LostChurn dashboard, go to Settings > Integrations and click Connect WooCommerce.
- Copy the generated API Key and Webhook Secret.
- In your WordPress admin panel, navigate to LostChurn > Settings.
- Paste the API Key and Webhook Secret into the corresponding fields.
- Enter your LostChurn Workspace ID (found in your LostChurn dashboard under Settings > General).
- Click Save and Verify. The plugin makes a test API call to confirm the credentials are valid.
Configuration
WooCommerce REST API
The LostChurn plugin uses the WooCommerce REST API to read subscription and order data. During activation, the plugin automatically creates a set of REST API credentials with the following permissions:
- Orders: Read and Write
- Subscriptions: Read and Write
- Customers: Read
If you prefer to create credentials manually, navigate to WooCommerce > Settings > Advanced > REST API, click Add Key, and assign the permissions listed above.
Webhook Delivery
The plugin registers the following WooCommerce webhook topics automatically:
| Webhook Topic | Endpoint |
|---|---|
subscription.payment_failed | https://webhooks.lostchurn.com/v1/woocommerce |
subscription.renewal_failed | https://webhooks.lostchurn.com/v1/woocommerce |
subscription.status_updated | https://webhooks.lostchurn.com/v1/woocommerce |
order.updated | https://webhooks.lostchurn.com/v1/woocommerce |
All webhook payloads are signed using the webhook secret you configured during setup. LostChurn verifies the X-WC-Webhook-Signature header on every incoming request using HMAC-SHA256.
Supported Events
| WooCommerce Event | LostChurn Action |
|---|---|
payment_failed | Creates a failed payment record, triggers retry evaluation |
renewal_failed | Creates a failed renewal record, triggers dunning sequence |
subscription_on-hold | Records at-risk subscription, triggers pre-cancellation campaign |
subscription_cancelled | Records churn event, triggers reactivation campaign if configured |
subscription_activated | Confirms subscription activation |
subscription_renewed | Marks recovery as successful, stops active dunning |
order_payment_complete | Updates recovery status, records successful payment |
How Recovery Works
- Detection: When a WooCommerce subscription renewal payment fails, the plugin sends the failure event to LostChurn in real time.
- Analysis: LostChurn analyzes the decline code from the payment gateway (Stripe, PayPal, etc.) and determines the optimal recovery strategy.
- Smart Retry: LostChurn schedules retries at optimal times via the WooCommerce REST API. The retry request triggers WooCommerce to re-attempt the charge through the original payment gateway.
- Dunning: In parallel, LostChurn sends personalized recovery emails and optional SMS messages to the customer with a payment update link.
- Resolution: When the payment succeeds (either via retry or customer action), WooCommerce fires a success event and LostChurn marks the recovery as complete.
If you use WooCommerce's built-in automatic retry feature (under WooCommerce > Settings > Subscriptions > Retry Rules), disable it to avoid conflicts with LostChurn's Smart Retry Engine. Navigate to WooCommerce > Settings > Subscriptions and set Automatic Retry to Disabled.
Admin Features
Order Meta Box
The LostChurn plugin adds a Recovery Status meta box to the WooCommerce order edit screen. This meta box displays:
- Current recovery status (Active, Recovered, Churned)
- Number of retry attempts and their results
- Dunning emails sent and open/click rates
- Link to the full recovery timeline in the LostChurn dashboard
Dashboard Widget
A LostChurn Recovery Summary widget is added to the WordPress admin dashboard. It shows:
- Failed payments in the last 30 days
- Recovery rate percentage
- Revenue recovered this month
- Active dunning campaigns
Provider-Specific Notes
Payment Gateway Compatibility
WooCommerce supports dozens of payment gateways. LostChurn works with any gateway that WooCommerce Subscriptions supports for automatic renewals, including:
- Stripe (via WooCommerce Stripe Gateway)
- PayPal (via WooCommerce PayPal Payments)
- Braintree
- Square
- Authorize.Net
- GoCardless
LostChurn maps decline codes from each gateway to its unified decline taxonomy for consistent recovery strategies.
Staging Environments
If you run a WooCommerce staging site, install the LostChurn plugin on staging with a separate API key. LostChurn detects staging environments and labels events accordingly, preventing test events from affecting production analytics.
Multisite Support
The LostChurn plugin supports WordPress Multisite installations. Each site in the network requires its own API key and workspace connection. Network-wide activation is supported.
API Rate Limits
LostChurn respects WooCommerce REST API rate limits. If your hosting provider enforces request limits, LostChurn queues retry requests and processes them within the allowed rate. For high-volume stores, consider a hosting plan with generous API rate limits or contact LostChurn support to optimize request batching.