***

title: Automatic retries & emails
subtitle: >-
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:

<Steps>
  <Step title="Payment retries" toc={false}>
    Automatic attempts to charge the customer.
  </Step>

  <Step title="Email notifications" toc={false}>
    Up to 6 emails, each containing a secure payment method update link. Each email is sent immediately after a failed payment attempt.
  </Step>

  <Step title="Failure handling" toc={false}>
    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
  </Step>
</Steps>

```mermaid
flowchart TD
    A[Payment fails] --> B[Retry schedule triggered]
    B --> C[Send email with payment update link]
    C --> D{Hard decline?}
    D -->|Yes| E[Pause retries → Send update PM email]
    E --> F{Payment method updated?}
    F -->|Yes| B
    D -->|No| G{Retries exhausted?}
    G -->|Yes| H[Apply subscription & invoice failure handling]
```

***

# 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.   |

```mermaid
gantt
    dateFormat  YYYY-MM-DD
    axisFormat  %b %d
    title Retry & Email Timeline
    section Retry & Email
    Retry 1             :a1, 2026-01-01, 1d
    Email 1             :a2, after a1, 1d
    Retry 2             :a3, after a2, 1d
    Email 2             :a4, after a3, 1d
    Retry 3             :a5, after a4, 1d
    Email 3             :a6, after a5, 1d
    Final Retry         :a7, 2026-01-21, 1d
    Final Email         :a8, after a7, 1d
```

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:

| 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.