← Blog
SaaSBillingMulti-TenancyPHP

Failed Payments in a CRM SaaS: Dunning and Suspension

A written SaaS failed payment dunning ladder with real day numbers, the webhook bugs that unfreeze accounts you froze, and why pause beats cancel buttons.

At 03:15 the billing cron fires, the gateway tries the card on file for a tenant paying $79 a month, and the issuer returns insufficient_funds. Nothing visible happens. That team logs in at nine and works a normal day. Three weeks later somebody notices the account has not paid since March, and the cardholder has left the company. The gap between a declined charge and a decision is where SaaS failed payment dunning lives, and most self-hosted CRM platforms have no policy for it - just an intention to “send reminders”.

We build and sell the multi-tenancy modules and SaaS platforms named below, so weigh the recommendations accordingly. Involuntary churn is the only churn you recover with a schedule rather than a roadmap, and almost nobody writes the schedule down.

Why SaaS failed payment dunning is an operations problem, not a payments one

Before you send anything, sort the failure. Three categories behave completely differently:

  • Soft declines - insufficient_funds, try_again_later, processing_error. The card is fine and the same charge will probably succeed on a different day - the only category where automatic retries earn their keep.
  • Hard declines - lost_card, stolen_card, pickup_card, invalid_account. No retry will ever succeed, and retrying is spam that trains the issuer to distrust your merchant account. Only a new card fixes it.
  • Authentication required - the SCA and 3-D Secure path in the UK and EEA. The charge completes only with the cardholder in a browser, so an off-session retry cannot resolve it. This one needs a link, not a retry.

A fourth case you can win early: a card expiring on 31 March is a failure visible in early February, because you already store exp_month and exp_year. A pre-dunning email at T-14 converts far better than the same request after a decline.

The ladder: five rungs with the day numbers written down

A ladder only works if the days and the email count are fixed in advance, so nobody makes a judgement call at 03:15. For a monthly $50-$150 CRM subscription:

DayRetryEmailState
01 failsReminder: update cardActive
3retry 2-Active + banner
5-Urgent: amount and planActive
7retry 3-Active, banner red
10retry 4, lastFinal warning: names the dateActive
14-Suspended: what is off, what is keptSuspended
44-30 days left to reactivateSuspended
90-Deletion in 14 daysPending deletion

Six emails across 90 days, four before anything is switched off. One reminder is not a ladder, and eight is harassment.

Why 14 days of grace period before suspension. It spans two weekends and two payday cycles, so a temporary cash-flow problem resolves itself inside the window, and a $79 charge never compounds into $158 - people pay one late invoice and argue about two.

Our products ship this shape rather than leaving you to assemble it: FeedbackPulse sends dunning notices in those four steps, LeadHub the same across five gateways, and the SaaS module for Concord CRM suspends overdue tenants from payment status when paired with the Invoicing module.

Two rules decide whether it converts. Every email needs a link that works without a password - the signed, single-use, expiring pattern you use for invitations - because whoever holds the company card rarely remembers the CRM login. And the final warning must name the date and the consequence: “Suspended on 14 March, and your booking calendar stops taking appointments” beats “Please update your billing information”.

What “suspended” has to mean in your schema

Two states are not enough. You need active, past_due, suspended and pending_deletion. past_due is the interesting one: the tenant works normally and only the banner changes. At suspension, decide four things explicitly:

  • Login. Block the workspace, but leave the billing page and reactivation reachable without a session. An account locked out of its payment form cannot pay you.
  • Export. Keep it enabled: an Article 20 request does not pause because an invoice is late, and both FeedbackPulse and LeadHub ship full data export.
  • Public surfaces. Here multi-tenant CRM differs from ordinary SaaS. A FeedbackPulse tenant has a public roadmap, changelog and feedback wall on their own subdomain; a LeadHub tenant has landing pages, forms and a booking calendar. Suspension takes those down, and the people who notice are your customer’s customers. Serve a neutral 503, and never render “suspended for non-payment” where a prospect can read it.
  • Reactivation. One click, instant. Both super-admin panels expose suspend, activate, restore and refund as first-class actions, and the FeedbackPulse superadmin adds payment management and audit logs.

The duplicate webhook that unfreezes the account you just froze

Gateways guarantee at-least-once delivery, not ordering, and a dunning state machine driven straight off inbound events will eventually cost you a customer.

The concrete failure: a retry succeeds at 10:02 and you mark the subscription active. At 10:05 the gateway redelivers invoice.payment_failed from 09:58, because your endpoint returned a 502 first time. A naive handler advances the dunning counter on a paid invoice and sends a final warning. The mirror image is worse - a stale customer.subscription.updated lands after you suspended a tenant and flips it back to active, so the account you froze consumes resources and never pays.

Three defences, in order of value:

  1. A unique index on (gateway, event_id). Insert the event row first, process second, so a duplicate is a constraint violation and a no-op, not a second state transition.
  2. A monotonic watermark per subscription. Store the created timestamp of the last event you applied and drop anything older. LeadHub carries Stripe webhook idempotency and an explicit out-of-order guard on PayPal, because the billing-subscriptions API reliably produces both problems.
  3. Never suspend on payload alone. Before any customer-visible change, re-read the subscription from the gateway API and act on what it says now. One extra HTTP call beats locking a paying customer out of their CRM.

Verify the signature, return 2xx fast, and log every event you accepted and what it changed - when a customer disputes a suspension, that log settles it.

Keeping the data you have stopped being paid for

A suspended tenant is not free. It occupies disk, lands in every backup, and under database-per-tenant it is another schema every migration walks - 200 suspended tenants is 200 extra migration runs per release. The SaaS module for Perfex CRM offers isolated databases, prefixed tables in one database, or a hybrid set at plan level. Either way, write the retention policy next to the ladder:

  • Day 90: dump the tenant to cold storage, drop the live schema, keep the dump 12 months. Reactivation becomes a restore rather than a signup - still a recovery.
  • Warn first, and make the warning cancellable. LeadHub sends deletion warnings before a scheduled hard-delete and treats erasure as a 30-day cool-off with a banner the tenant can reach.
  • Do not let deletion cascade into your accounting. LeadHub keeps tax receipts alive through tenant erasure with ON DELETE SET NULL, because invoices carry a 7-10 year statutory retention in most of Europe. A ladder ending in DELETE CASCADE through your invoice table is a compliance incident wearing a cleanup script.

Pause without data loss beats a cancel button

A cancel button is a one-way door that discards your strongest retention asset: switching cost. Reactivating a paused tenant is a click; returning after cancellation means re-importing contacts, re-inviting the team and rebuilding pipelines.

FeedbackPulse lets tenants pause a subscription without losing data, and that is what belongs in front of anyone reaching the cancel screen or the day-14 email. Guardrails: cap the pause at three months, keep the card on file, auto-resume with a warning a week before the first charge.

The other lever is price. The Perfex module’s coupon engine is built for it: percentage or fixed discounts, applied once or auto-applied to every recurring invoice, with per-plan rules aimed at win-back campaigns. The arithmetic is not close - 30% off for three months on a $79 plan costs about $71 to hold a $948-a-year account, so one success in three still pays. But discounting a tenant whose card was stolen achieves nothing; that is a hard decline.

The ladder is worthless if the cron stops

All of this runs on a schedule, and on self-hosted PHP that schedule is cron. When it dies, no reminders go out, no suspensions fire, no invoices generate, and the failure stays silent until month end. Monitor the job, not the homepage: alert if the billing task has not written a row in 26 hours. LeadHub ships a health endpoint probing database, cache and storage with a 200/503 answer, and both platforms support URL-based cron on shared hosts.

Then watch one number monthly - the share of tenants entering dunning who pay before suspension. The Perfex module’s SaaS analytics dashboard and LeadHub’s super-admin churn reporting both surface it. When recovery drops, the cause is almost never the ladder: it is deliverability, or a broken card link.

Write it down before you need it

  1. Classify declines as soft, hard or authentication-required, and route each differently.
  2. Send the pre-dunning email 14 days before every card expiry you can already see.
  3. Fix the ladder in code: emails on days 0, 5, 10 and 14, retries on days 3, 7 and 10.
  4. Add a unique index on (gateway, event_id) and re-read gateway state before any suspension.
  5. Define past_due and suspended separately, and make public pages fail as a neutral 503.
  6. Set the day-90 dump-and-drop rule, with a cancellable warning and invoices exempt from any cascade.
  7. Put pause, not cancel, as the primary button on that screen.

Start with number four. Everything else here costs you money slowly, but an out-of-order webhook suspending a customer who has already paid costs you that customer this afternoon.