WooCommerce Plugin
Install the LostChurn WordPress plugin to recover failed WooCommerce Subscriptions payments automatically.
The LostChurn WooCommerce plugin hooks into WooCommerce Subscriptions to detect payment failures in real time and recover them using AI-optimized retry scheduling and personalized dunning.
What You Get
After installation, the plugin adds:
- Recovery Status Meta Box -- Appears on every WooCommerce order edit screen showing the current recovery status (Active, Recovered, Churned), retry attempts, dunning emails sent, and a link to the full timeline in LostChurn.
- Dashboard Widget -- A "LostChurn Recovery Summary" widget on your WordPress admin dashboard showing failed payments, recovery rate, and revenue recovered in the last 30 days.
- Settings Page -- Configure your API key, webhook secret, and enable/disable recovery under LostChurn > Settings.
- One-Click Retry -- Trigger a manual retry from any order's meta box without leaving WordPress. Status polling updates the result via AJAX.
Requirements
Before installing, confirm your environment meets these requirements:
| Requirement | Minimum Version |
|---|---|
| WordPress | 6.0 |
| WooCommerce | 5.0 |
| WooCommerce Subscriptions | Active license required |
| PHP | 7.4 |
| HTTPS | Required on your site |
The plugin declares HPOS (High-Performance Order Storage) compatibility, so it works with both the legacy post-based storage and the new custom order tables.
Installation
From the WordPress Plugin Directory
- In your WordPress admin, go to Plugins > Add New.
- Search for LostChurn.
- Click Install Now, then Activate.
Manual Upload
- Download the plugin ZIP from your LostChurn dashboard under Settings > Integrations > WooCommerce.
- In WordPress, go to Plugins > Add New > Upload Plugin.
- Upload the ZIP file and click Install Now, then Activate.
If WooCommerce is not installed, the plugin displays an admin notice with a link to install WooCommerce. The plugin will not activate without WooCommerce present.
Enter Your API Key
- In your LostChurn dashboard, go to Settings > Integrations and click Connect WooCommerce.
- Copy the generated API Key and Webhook Secret.
- In WordPress, go to LostChurn > Settings.
- Paste the API Key and Webhook Secret.
- Enter your LostChurn Workspace ID (found under Settings > General in your LostChurn dashboard).
- Click Save and Verify. The plugin tests the credentials and confirms the connection.
Webhook Auto-Registration
The plugin automatically registers webhooks with WooCommerce during activation:
| 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 payloads are signed with your webhook secret. LostChurn verifies the X-WC-Webhook-Signature header using HMAC-SHA256 on every request.
The plugin also hooks into woocommerce_subscription_payment_failed for instant, real-time failure detection before the webhook delivery cycle.
How Recovery Works
- Detection -- A subscription renewal payment fails. The plugin sends the event to LostChurn immediately.
- Analysis -- LostChurn extracts the decline code from your payment gateway (Stripe, PayPal, Braintree, etc.) and determines the optimal strategy.
- Smart Retry -- LostChurn schedules retries at ML-optimized times via the WooCommerce REST API. WooCommerce re-attempts the charge through your original gateway.
- Dunning -- In parallel, LostChurn sends personalized recovery emails (and optional SMS) with a payment update link.
- Resolution -- When the payment succeeds, WooCommerce fires a success event and LostChurn marks the recovery complete.
If you use WooCommerce's built-in automatic retry rules, disable them to avoid conflicts. Go to WooCommerce > Settings > Subscriptions and set Automatic Retry to Disabled.
Payment Gateway Compatibility
LostChurn works with any gateway that WooCommerce Subscriptions supports for automatic renewals:
- Stripe (via WooCommerce Stripe Gateway)
- PayPal (via WooCommerce PayPal Payments)
- Braintree
- Square
- Authorize.Net
- GoCardless
Decline codes from each gateway are mapped to LostChurn's unified decline taxonomy for consistent recovery strategies.
Troubleshooting
Plugin activation fails
- Confirm WooCommerce is installed and activated.
- Confirm PHP 7.4 or later is running (
phpinfo()or Tools > Site Health). - Check that WooCommerce Subscriptions has an active license.
"Invalid API Key" on save
- Copy the API key again from your LostChurn dashboard. Ensure no extra spaces were included.
- Confirm the key is for the correct workspace.
Webhooks not delivering
- Go to WooCommerce > Settings > Advanced > Webhooks and check that LostChurn webhooks are listed with status "Active."
- If webhooks are missing, deactivate and reactivate the plugin to re-register them.
- Verify your site is reachable over HTTPS from the public internet. Localhost and
.localdomains cannot receive webhooks.
Staging environments
Install the plugin on staging with a separate API key. LostChurn detects staging environments and labels events accordingly. Test events do not affect production analytics.
Multisite support
The plugin supports WordPress Multisite. Each site in the network requires its own API key and workspace connection. Network-wide activation is supported.
Next Steps
- Recovery campaigns -- configure retry timing and dunning sequences
- Shopify integration -- if you also sell on Shopify
- BigCommerce integration -- if you also sell on BigCommerce