Recover failed subscription renewals automatically

When a subscription renewal fails, Flopay now takes over automatically. Rather than leaving the subscription in a past_due state for merchants to handle manually, Flopay schedules a series of intelligent retries across the recovery window, adapting the cadence to the subscription's billing interval and the reason the initial charge was declined.

Subscriptions stay honest throughout: billing dates and agreed terms never advance on a failed attempt, a recovered charge resumes the normal cycle exactly once, and a subscription only expires when the recovery window is fully exhausted or every eligible payment method has reached a definitive terminal decline.

Decline-aware retry schedules

Retry timing reflects the subscription's own cadence. A daily subscription retries through a 20-hour window; weekly through day 6; monthly through day 27; and annual subscriptions through day 60. Longer billing intervals scale these windows proportionally, and retries never cross the next billing boundary.

Each attempt re-evaluates the available saved payment methods, so a method that becomes available during recovery (such as a freshly updated card) can complete the renewal without merchant intervention.

Approval-signal timing

Retry timing incorporates measured signals that move approval odds: day-of-month patterns, typical payday windows, issuer behavior, and time-of-day. This is based on observed approval data, not assumptions, so retry slots shift as signals change.

Client-configurable policies

Merchants can tailor dunning policies through their dashboard settings to match their subscriber base and risk tolerance, within guardrails that keep lifecycle events accurate.

Recovery visibility

A new read endpoint, GET /v1/subscriptions/:id/recovery, returns the full recovery history for any subscription: every campaign, every retry round, and the outcome of each attempt. Subscription timelines include a subscription.recovery_retry future event when a retry is already scheduled, so support tools no longer show a normal upcoming rebill while recovery is in progress.

Recovery reporting

GET /v1/subscriptions/stats and GET /v1/admin/subscriptions/stats now include a dunningRecovery object with recoveredRebillCount and recoveredRebillRevenue. These figures are a strict subset of existing rebillCount and rebillRevenue totals, so they slot into existing reporting without changing how gross metrics are calculated.

The Dashboard's Rebill Sales and Rebill Revenue cards on the /overview page now surface recovered rebills alongside first-attempt successes, and the customer journey and subscription detail views show automated recovery activity in context.

What's included

• Subscriptions: Structured recovery window with decline-aware retry scheduling, cadence-proportional windows, and honest lifecycle events throughout.
• Webhooks: Existing subscription and invoice event shapes are unchanged; subscription.recovery_retry is a new additive future event code on timeline responses.
• Reporting: dunningRecovery object added to subscription stats endpoints for merchant and admin scopes.
• Dashboard: Rebill Sales and Rebill Revenue cards include recovered rebills; customer journey and subscription detail surfaces show recovery history inline.

Developer notes

The stats endpoint change is additive: existing request parameters, authentication, and status codes are unchanged. Clients with strict response schema validation should accept the new dunningRecovery object on GET /v1/subscriptions/stats and GET /v1/admin/subscriptions/stats.

Clients with strict timeline event validation should accept the new subscription.recovery_retry future event code. The recovery history endpoints follow the standard paginated list shape: data, page, limit, pages, and total.

No SDK upgrade, configuration change, or migration is required for existing subscriptions.

Why it matters

Involuntary churn (a renewal lost to a temporary decline) represents not just one missed payment but every future payment in that subscription's lifetime. Automatic recovery converts those moments into confirmed revenue without asking the customer to re-enter payment details or the merchant to build retry logic themselves. Accurate lifecycle events and full recovery visibility mean merchants can report on and explain every recovery without reconciling data across separate sources.