Automatic retries & emails
PaymentKit’s dunning system automatically recovers failed payments through retries and emails while giving you control over subscription and invoice outcomes when all payment attempts fail.
How dunning works
Dunning is composed of three coordinated actions:
Retry schedules
PaymentKit automatically retries failed payments according to the subscription billing cycle. The schedule varies by cycle length.
- Retry interval: Time between retry attempts
- Final retry: Last retry before applying failure handling
- Retry attempts:
floor(final_retry / retry_interval) + 1, then capped by the profile’s max retries (adaptive defaults: 3 daily, 4 short, 8 standard, 10 long)
Cycle lengths & parameters
max_dunning_window defaults to 30 days. Standard and long cycles share the same interval and final-retry formula; they differ only in the adaptive profile’s default max retries (8 vs 10).
Emails are sent at the retry steps configured in the profile’s email map — typically the first at the initial failure and the last at the final retry, with additional steps for longer cycles — capped at 5 per cycle and no more than one every 24 hours. The timeline below is illustrative; emails do not necessarily follow every retry.
Intervals adjust for cycle type; Short and daily cycles would compress accordingly.
Retry behavior by profile type
How retries are scheduled depends on whether you’re using an adaptive (system default) or custom dunning profile.
Adaptive profiles: Intelligent retries
Adaptive profiles inject additional retry attempts based on the decline reason:
Liquidity retries target paydays when customers are most likely to have funds available. This significantly improves recovery rates for insufficient funds declines.
These intelligent retries don’t run alongside the standard schedule — they’re reconciled with it through a 24-hour deduplication window. When more than one retry falls in the same window, the highest-priority one fires (priority order: final > technical > liquidity > standard).
Custom profiles: Fixed intervals
Custom profiles use your configured retry_interval_hours for every retriable decline, with no decline-type-specific timing:
- TECHNICAL declines → fixed interval (no T+1h/T+2h fast-path)
- SOFT declines → fixed interval (no liquidity/payday targeting)
- HARD declines → payment-method update, the same as adaptive profiles (the fallback-card cascade is not profile-specific)
Retries occur at predictable, fixed intervals.
Choose custom profiles when you need deterministic retry schedules, have compliance requirements for fixed timing, or want full control over every retry attempt.
The renewal wall applies to both
The renewal wall — 1 hour before the current billing period ends — is not an adaptive behavior. It is a system constraint that profile configuration cannot override, and it binds custom profiles exactly as it binds adaptive ones:
- No retry is scheduled at or after the wall.
- If your fixed interval would place the next retry past the wall, that attempt is pulled back onto the wall and runs there as the final retry. Choosing a custom profile does not forfeit the last attempt of the cycle.
- Once the wall has passed, dunning ends and your configured failure handling is applied.
The wall clamps your schedule rather than extending it. If your configured retries run out before the wall, dunning ends there — no extra attempt is added beyond your max_retries.
A retry_interval_hours close to or longer than the billing cycle means most of your configured retries never run: the cycle hits the wall first and the attempt that would have crossed it becomes the final one. Keep the interval well under the cycle length to use the full retry budget.
One-time invoices have no next billing period and therefore no renewal wall; their retries are bounded by the one-time retry window instead.
Failure handling settings
When retries are off or exhausted, PaymentKit applies these rules:
The invoice status choice takes effect only when the subscription is paused. When the subscription is cancelled or left active (past-due), the invoice is always marked uncollectible.
For most businesses, cancelling the subscription and marking the invoice uncollectible will give you the cleanest reporting.
Hard decline handling
When a payment method returns a hard decline (expired card, closed account, invalid card number, stolen/lost card), PaymentKit:
- Marks the payment method as declined for this specific invoice
- Attempts the next payment method in the customer’s payment method list
- Repeats until success or all payment methods have hard declined
If all payment methods hard decline, the invoice moves to “Update payment method” status and:
- Automatic retries stop — no usable payment method remains to charge
- The customer is notified to update their payment method
- Adding a valid payment method resumes collection; if the dunning cycle has already ended, the new method starts a fresh cycle
Hard decline tracking is per-invoice. A payment method that fails on one invoice may still work for other invoices.
Pausing retries on an invoice
You can pause a failing invoice’s automatic retries without voiding the invoice or cancelling the subscription — useful when you’ve agreed a different arrangement with a customer and want to collect the invoice by hand for now.
Pausing is done by switching the invoice’s collection method from automatic to manual. Send a PATCH to the invoice:
- Allowed only while the invoice is open or past due (a paid, voided, draft, or uncollectible invoice cannot be changed).
- Automatic retries stop immediately and the current dunning cycle is paused, not ended.
- The invoice stays open and payable: your customer can still pay it from a payment link or the billing portal, and you can still trigger a manual collection. A payment at any time closes out the paused cycle.
To resume automatic retries, switch the collection method back to automatic:
- Requires a usable default payment method on the invoice or its subscription (otherwise the request is rejected).
- If the billing period is still open, the next retry is re-scheduled and dunning continues from where it paused.
- If the billing period has already ended (the renewal wall has passed), the cycle is closed out instead of retrying — the same way a normal cycle ends at the wall. No charge is attempted.
Pausing is per invoice. It does not change the subscription’s own collection method and does not affect other invoices. If you never resume a paused invoice, PaymentKit closes out its dunning once the billing period ends — it is never left retrying and is never charged automatically again.
Edge cases during dunning
PaymentKit gracefully handles scenarios where external changes occur during active dunning:
Invoice manually paid
If an invoice is marked as paid outside the normal payment flow (e.g., manual payment recorded, payment via alternative channel), dunning stops immediately:
- No further automatic retries are scheduled
- Dunning status transitions to “Completed”
- Subscription state updates based on remaining unpaid invoices
Invoice voided
When an invoice is voided during dunning:
- Dunning ends with the terminal status “Invoice voided” (distinct from “Completed”)
- The subscription continues if other invoices are still active
- No end behavior is applied (voiding is explicit cancellation of the debt)
Subscription cancelled externally
If a subscription is cancelled while in dunning (e.g., via API, admin action, or customer request):
- Scheduled payment retries are skipped
- Outstanding invoices remain in their current state
- End behavior for existing invoices follows your failure handling settings
Payment method changes
During active dunning:
- Method deleted: The subscription’s own payment method cannot be deleted (
409,error_code: payment_method_in_use). Change the subscription’s payment method first: the open invoice moves to the new method and the retries resume on it. Other methods can be deleted - Method added: New method is included in the next retry attempt
- Default method changed: New default is prioritized in the retry order