BillingDunning & Recovery

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.

View as Markdown

How dunning works

Dunning is composed of three coordinated actions:

1

Payment retries

Automatic attempts to charge the customer.

2

Email notifications

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

3

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 lengthRetry intervalFinal retryNotes
Long (≥7 days)4 daysmin(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 daysmin(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.
Daily23 hoursmin(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.

Failure handling settings

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

TypeOptionDescription
Subscription statusCancel subscriptionCancel subscription if all retries fail
Keep subscription active (past-due)Leave subscription active even if all payments fail
Invoice statusMark as uncollectibleTreat invoice as uncollectible after all retries fail
Leave invoice openKeep invoice open for future collection attempts

For most businesses, cancelling the subscription and marking the invoice uncollectible will give you the cleanest reporting.