How dunning works

Dunning is composed of three coordinated actions:

Payment retries

Automatic attempts to charge the customer.

Email notifications

Up to 6 emails, each containing a secure payment method update link. Each email is sent immediately after a failed payment attempt.

Failure handling

Controls what happens if all payment attempts ultimately fail:

Subscription status: Cancel subscription / leave subscription active (past due)
Invoice status: Mark invoice as uncollectible / leave invoice open

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

Cycle lengths & parameters

Cycle length	Retry interval	Final retry	Notes
Long (≥7 days)	4 days	`min(cycle_length -1, max_dunning_window, payment_terms-1, next_invoice_date - invoice_due_date -1)`	Up to 6 emails. The first email is sent on the invoice due date. Each subsequent email is sent immediately after a retry. The final email is sent on the last retry day.
Short (2–6 days)	2 days	`min(cycle_length -1, payment_terms-1, next_invoice_date - invoice_due_date -1)`	Number of emails depends on the number of retries. Each email is sent immediately after a retry, with the first email on the invoice due date and the final email on the last retry day.
Daily	23 hours	`min(23h, payment_terms*24h - 1h, next_invoice_date - invoice_due_date -1h)`	Fewer emails due to short intervals. The first email is sent on the invoice due date, each email occurs immediately after a retry, and the final email is sent on the last retry time.

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:

Decline Type	Extra Retries	Timing
TECHNICAL (network timeout, processor error)	Technical retries	T+1h and T+2h after failure
SOFT (insufficient funds)	Liquidity retries	1st/15th of month or Fridays at 9 AM
All types	Final retry	1 hour before billing cycle ends

Liquidity retries target paydays when customers are most likely to have funds available. This significantly improves recovery rates for insufficient funds declines.

Standard retries (per the schedule above) continue in parallel with these intelligent retries.

Custom profiles: Fixed intervals

Custom profiles use your configured retry_interval_hours for all decline types:

TECHNICAL declines → standard interval retry
SOFT declines → standard interval retry
HARD declines → standard interval retry

No intelligent timing adjustments are applied. 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.

Failure handling settings

When retries are off or exhausted, PaymentKit applies these rules:

Type	Option	Description
Subscription status	Cancel subscription	Cancel subscription if all retries fail
	Keep subscription active (past-due)	Leave subscription active even if all payments fail
Invoice status	Mark as uncollectible	Treat invoice as uncollectible after all retries fail
	Leave invoice open	Keep invoice open for future collection attempts

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 transitions to “Update payment method” status and:

Automatic retries pause (no point retrying with the same failed methods)
Customer receives an email to update their payment method
When a new payment method is added, retries resume automatically

Hard decline tracking is per-invoice. A payment method that fails on one invoice may still work for other invoices.

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 gracefully with status “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: Next retry uses remaining methods; if none available, transitions to “Update payment method”
Method added: New method is included in the next retry attempt
Default method changed: New default is prioritized in the retry order