Billing Health
Subscription billing fails quietly. A cron job stops running, a webhook secret goes missing after a move, or a customer’s card expires, and the first sign is a dip in revenue a month later. By then the customers have already been billed late, or not at all.
Billing Health puts every billing problem on one screen: renewals that are late or stuck, subscriptions with no saved payment method, decline reasons, and payment provider webhooks that never arrived. It offers safe fixes that never charge or email anyone, and it can email customers whose saved card expires before their next renewal.
Turn On the Module
- Go to FluentCart → Stackless and switch on Billing Health on the Stackless Dashboard.
- Open FluentCart → Billing health.
It needs FluentCart 2.3 or newer. Administrators and store managers with FluentCart’s store settings permission can open the screen and run fixes. The gateway checks show for each gateway you’ve added through Payment Gateways.
Read the Screen
The top of the screen counts Problems, Warnings and Notes. When there is nothing to look at, it says “Nothing needs your attention.” Otherwise each area with something to report gets its own section, problems first:
- Stackless and FluentCart: the store itself.
- Subscriptions and renewals: renewals, charges, saved payment methods and declines.
- One section per gateway: Stripe (Stackless), PayPal (Stackless), Polar, Paddle, Dodo Payments and Creem, copies included.
Each finding says what’s wrong and what it means for billing, with an Open button to the right screen and, where one exists, a fix button. Reports name subscription and order numbers only, never an email address, a card number or a key.
What It Checks
The Store
- The site is a copy of the live store, so automatic billing and customer emails are paused. See copies of the live store.
- The live site is in FluentCart’s test mode while a Stackless gateway is on, so customers can’t pay with real cards.
- FluentCart’s hourly task isn’t scheduled. Without it, no store-billed subscription renews.
- Scheduled billing tasks are more than an hour late, or billing tasks failed in the last 7 days.
- Code has switched off FluentCart’s automatic charging while subscriptions still need it.
Subscriptions and Renewals
- A subscription your store bills is more than 2 hours past its renewal date with no renewal invoice.
- A subscription Polar, Paddle, Dodo Payments, Creem or Stripe Managed Payments bills is 2 days past its renewal date, which usually means the renewal webhook never arrived.
- An automatic charge failed and won’t be retried, failed and will be retried, or has waited more than 2 days for the payment provider.
- A subscription renews through Stripe (Stackless) or PayPal (Stackless) but has no usable saved payment method, so the next charge will fail.
- Saved cards expire before their next renewal.
- Payments were hard declines in the last 30 days.
Payment Gateways
- API keys, tokens or a client secret are missing for the store’s current mode, so the gateway stays hidden at checkout.
- Stripe keys don’t match the store’s mode, such as a test key on a live store.
- The webhook secret or webhook ID is missing, so refunds, renewals and cancellations from the provider don’t reach the store.
- No signed webhook has ever arrived, or the last one was for the other mode.
- Recent webhook problems from the last 7 days, in a table with the event, its status (Stuck or Failed) and a note.
FluentCart’s own Stripe and PayPal don’t get a gateway section. Their subscriptions still show in the renewal checks.
Run a Fix
Some findings have a fix. Click it, read what it will do, then click Run this fix or Cancel. No fix charges a customer, and outgoing email is blocked while it runs. Each one is logged in the Fix log with the time, the user and the result.
- Schedule it again: schedules FluentCart’s five-minute, hourly and daily tasks again, the way FluentCart does when it’s activated. It’s offered on the live store only.
- Sync from the provider: reads up to 20 overdue provider-billed subscriptions and their renewal payments from the provider, and updates the store to match. Each one gets a “Synced from the provider” entry in its log.
- Clear the list: removes recorded webhook failures once you’ve fixed their cause. It clears them for every gateway at once. Nothing changes at the provider, and new failures show up again.
Decline Reasons
When Stripe (Stackless) declines a payment at checkout or on a renewal, or PayPal (Stackless) declines a renewal, the order gets a warning in its activity log: “Payment declined” or “Renewal charge declined”, with the provider’s code, its kind and what to do. The same declines from the last 30 days fill the Recent declines table under Subscriptions and renewals.
| Kind | What it means |
|---|---|
| Hard decline | The bank will not approve this payment method again. Retrying it will fail; the customer needs to use another one. |
| Insufficient funds or limit | A later retry can work once the customer has funds or the limit resets. |
| Needs the customer | The bank or PayPal wants the customer to confirm this payment, so it cannot be charged automatically. |
| Provider unreachable | The provider did not answer, so this may not be a decline. Check the payment at the provider before charging again. |
| Soft decline | The bank declined without a lasting reason. A retry can work. |
Buyers never see the kind or the advice. A Stripe (Stackless) buyer sees a plain message such as “Your card has insufficient funds.”, and declines that point to fraud read “Your card was declined. Try another card or payment method.”
The gateways record decline reasons on orders whether or not Billing Health is on. The module adds the screen.
The Card-Expiring Email
A card that expires before the next renewal is a failed payment you can see coming. Turn the email on under Stackless → Settings → Billing Health:
- Email customers when the saved card expires before the next renewal: off by default.
- Days before the renewal: how far ahead the daily check looks, from 1 to 60. The default is 14.
Each day, Billing Health looks at every active or trialing subscription that FluentCart renews itself with a saved card through Stripe (Stackless) or one of its copies, bought in the store’s current mode and renewing within that many days. When the saved card runs out before the renewal date, the customer gets one plain-text email for that card and expiry.
The subject reads “Your card expires before your next Your Store renewal”. The email names the card, such as Visa ending in 4242, the product, the expiry month and the renewal date, and links to the subscription in the customer’s account so they can update the payment method before then. A new card, or a new expiry on the same card, can bring another email. The subscription’s log records “Card-expiring email sent”.
With the email off, the screen still lists cards that expire before their renewal, as a note.
Site Health
Billing Health also adds a Stackless billing test to Tools → Site Health. It reports critical when there are problems, recommended when there are only warnings, and links to the Billing health screen.
Limits
- Decline reasons come from Stripe (Stackless) and PayPal (Stackless) only. Polar, Paddle, Dodo Payments, Creem and Stripe Managed Payments don’t record them.
- The card-expiring email covers Stripe (Stackless) only. It doesn’t cover PayPal (Stackless), FluentCart’s own Stripe, or providers that bill renewals themselves: Polar, Paddle, Dodo Payments, Creem and Stripe Managed Payments.
- The email has no unsubscribe link. It’s a service message about one subscription.
- Each section shows up to 20 webhook events and 20 declines, and long lists of subscriptions show the first 20 numbers.
- PayPal webhook failures come from PayPal’s own log and have no Clear the list button.
- There’s no export, and the screen has no filters.
- On copies of the live store, the card-expiring email waits until you confirm the site is the live one.
For Developers
| Hook | Type | Use |
|---|---|---|
gtfc/billing_health/sources | filter | Add your own section: ($sources), an array of id => callable that returns a label, issues, events and declines. |
gtfc/billing_health/fix | filter | Run a fix your source offers: ($result, $source, $fix). Return a message, a WP_Error, or null when the fix isn’t yours. |
gtfc/billing_health/fix_description | filter | The text on the confirmation step for your fix: ($description, $source, $fix). |
gtfc/billing_health/card_update_url | filter | Where the card-expiring email links: ($url, $subscription). The subscription in FluentCart’s customer portal by default. |
gtfc/billing_health/card_expiring_sent | action | Runs after a card-expiring email is sent: ($subscriptionId, $key). |
Send customers to your own billing page instead of the portal:
add_filter('gtfc/billing_health/card_update_url', function ($url, $subscription) {
return home_url('/account/billing/');
}, 10, 2);