Find Billing Problems with Billing Health
A subscription store loses money quietly. A renewal fails and nobody notices, a webhook stops arriving or a scheduled job dies halfway. You find out when a customer writes in to ask why their access stopped.
The Billing Health module puts everything that can stop money coming in on one screen: on-hold and overdue subscriptions, renewal charges that never finished, automatic renewals with no saved payment method, failed scheduled actions, payment gateway setup and webhook problems and why customers cancelled lately. It fixes what Stackless can safely fix and logs every fix.
Turn On Billing Health
- Go to Stackless → Dashboard and switch on Billing Health. It’s off by default.
- Open Stackless → Billing Health.
The screen runs every check again each time you open it, so there’s nothing to schedule. It needs the manage_shop_settings capability, which EDD gives to administrators and shop managers.
What the Screen Shows
Three counters sit at the top: Problems, Warnings and Notes. When all three are zero, the screen says “Nothing needs your attention.”
Below them, each source that found something gets its own section: Stackless first, then Subscriptions and each payment gateway module you have on. A source with nothing to report doesn’t show. Inside a section, Problems come first, then Warnings, then Notes. Each item has a short explanation, and many have an Open button that takes you to the subscriptions, orders, logs or settings involved.
A check that breaks doesn’t take the screen down with it. Its section shows “This check failed to run.” with the error, and the other sections still load.
Stackless Checks
- Automatic billing is paused on this site (Problem): the site looks like a copy of the live store, so Stackless doesn’t charge saved payment methods, retry payments or email customers here. If this is the live store, confirm it in the notice at the top of the admin.
- Stackless scheduled actions failed in the last 7 days (Warning): lists each failed job with a count. Open goes to Tools → Scheduled Actions, filtered to failed Stackless actions.
- Leftover locks from interrupted requests (Note): locks expire on their own, so this is housekeeping. Clear old locks removes only locks older than an hour.
Subscription Checks
These show when the Subscriptions module is on:
| Check | Badge | What to do |
|---|---|---|
| Subscriptions on hold after a failed or unpaid renewal | Warning | Open lists them. The detail says how many won’t be retried because the bank declined the card for good or needs the customer to confirm. Those wait for the customer to pay or change the payment method. |
| Subscriptions past their renewal date with no renewal scheduled | Problem | Click Rebuild their schedules. Each one renews within a minute. |
| Renewal charges that started but never finished | Problem | A request stopped mid-charge more than an hour ago. Open shows your pending EDD orders. Check the payment at your provider before you use Retry failed payment on the subscription, so the customer isn’t charged twice. |
| Renewals waiting more than a day for the payment provider | Warning | Bank debits can take a few days. Otherwise check that the provider’s webhook reaches your site. |
| Subscriptions that renew automatically but have no saved payment method | Warning | Their renewals will fail and go to failed-payment retries. Ask the customers to add a payment method, or switch them to manual renewal. |
| Why customers cancelled in the last 30 days | Note | Each reason from the cancellation form with a count, most common first. |
Overdue means an active or trial subscription that Stackless bills itself, due more than two hours ago and less than 60 days ago, with nothing unpaid and no renewal queued. Subscriptions your payment provider bills are left out, because the provider runs their schedule.
Payment Gateway Checks
Each payment module you have on adds its own section. Most checks only run for gateways you’ve turned on under Downloads → Settings → Payments:
| Gateway | What it checks |
|---|---|
| Stripe and Stripe Managed Payments | Missing API keys for the selected mode or keys from the other mode, a missing webhook signing secret, Managed Payments events missing from the webhook, EDD taxes turned on while Managed Payments is enabled, test mode on the live store and webhooks arriving for the other mode. |
| PayPal | A missing client ID or secret, a missing webhook ID, sandbox mode on the live store and Fastlane turned on without the card fields. |
| Square | A missing application ID, access token or location, a missing webhook signature key, a location currency that differs from the store’s, sandbox mode and webhooks that failed recently. |
| Mollie | No API key for the selected mode, test mode, renewal charges pending for over two weeks and webhooks that failed recently. |
| Razorpay | No API keys or webhook secret for the selected mode, test mode, renewal debits pending for over five days and webhooks that failed recently. |
| Creem, Paystack, Flutterwave and Mercado Pago | A missing key or a key for the other mode, webhooks that can’t be verified, no webhook received yet and test mode. |
| Polar, Paddle and Dodo Payments | Webhooks that failed or got stuck in the last 7 days. |
When a gateway logged webhook problems, its section also lists them in a Recent webhook problems table with When, Event, Status and Note, so you can match them against the provider’s own delivery log.
Fix What Stackless Can Fix
Three items come with a fix button:
- Rebuild their schedules, on overdue subscriptions: rebuilds each subscription’s renewal schedule from its dates and adds the note “Renewal schedule rebuilt from Billing Health.” The renewal then runs the normal way, which charges the saved payment method or emails the invoice.
- Clear old locks: deletes leftover locks older than an hour, and never one that a running request has just taken.
- Create the webhook, on a missing Square webhook signature key when an access token is saved: creates the webhook at Square and saves its signature key. If Square sends no key back, the fix fails with “Square did not return a signature key. Add the webhook by hand.”
The first two only re-run Stackless’s own steps and change nothing at your payment provider. Everything else on the screen is a pointer: open the item and act on the subscription, order or gateway settings it names.
Who Can Run Fixes and the Fix Log
Fixes need the same manage_shop_settings capability as the screen. They run from buttons on the screen, so nobody triggers one by following a link.
Every fix lands in the Fix log at the bottom of the screen, whether it worked or not:
- When: the date and time.
- Who: the username of the person who ran it.
- Fix: the source and the fix, such as
subscriptions · resync_overdue. - Result: the message, such as “Rebuilt the schedules of 3 subscriptions.” A failed fix starts with “Failed:”.
The log keeps the last 100 fixes in the stackless_edd_billing_health_log option and shows the latest 30.
Site Health
Billing Health adds a Stackless billing test to Tools → Site Health, with a Payments badge. It reads the same checks:
- No Problems or Warnings: “Stackless billing has no problems”.
- Warnings only: a recommended item, such as “Stackless billing: 0 problems, 2 warnings”.
- Any Problem: a critical item with the same counts.
Notes don’t change the result. The test links to the screen with Open Billing Health.
Limits
- The screen shows what’s wrong right now. It doesn’t email you, and it keeps no history apart from the fix log.
- There are three fixes: rebuilding overdue schedules, clearing old locks and creating the Square webhook. Everything else needs you to act on the subscription, order or gateway.
- Checks stop counting at a cap, such as 200 subscriptions or 50 orders per check, and list up to 20 numbers. On a large store, fix what’s listed and reload.
- The overdue check looks back 60 days. Subscriptions overdue for longer don’t show.
- Cancellation reasons come only from the customer cancellation form. They’re missing when Ask why they cancel is off, and when you cancel from the admin.
- Subscription checks need the Subscriptions module, and each gateway’s checks need its module.
For Developers
Other code can add a section with stackless_edd_health_sources and run its own fixes with stackless_edd_health_fix. Use a lowercase source ID other than stackless. A source returns a label, issues and events. Issues take severity (error, warning or info), title, detail, url, fix and fix_label. Events take type, status, note and at, and up to 20 show.
The fix filter gets the result so far, the source ID and the fix key. Return a message on success, a WP_Error on failure or the value you got when the fix isn’t yours. Every call is written to the fix log.
add_filter('stackless_edd_health_sources', function ($sources) {
$sources['my_crm'] = function () {
$failed = (int) get_option('my_crm_sync_failures', 0);
return [
'label' => 'CRM sync',
'issues' => $failed ? [[
'severity' => 'warning',
'title' => sprintf('%d customer syncs failed.', $failed),
'fix' => 'reset',
'fix_label' => 'Reset the counter',
]] : [],
];
};
return $sources;
});
add_filter('stackless_edd_health_fix', function ($result, $source, $fix) {
if ($source !== 'my_crm' || $fix !== 'reset') {
return $result;
}
update_option('my_crm_sync_failures', 0);
return 'Counter reset.';
}, 10, 3);
For more hooks, see Hooks and Functions.