> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bouclay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Failed payments

> How Bouclay retries a failed renewal, emails the customer, and what happens if it never succeeds

Cards fail: not enough money, an expired card, a bank having a bad day. Most of these payments can be recovered if you try again and tell the customer. Bouclay does both on its own, a process often called **dunning**.

## What happens when a renewal fails

**1. The subscription turns past due**

The invoice stays `open`, and the subscription becomes `past_due`. The customer **keeps access** while Bouclay retries, because locking out a paying customer over one decline turns a recoverable payment into a cancellation.

**2. The customer is told**

They get an email saying the payment failed, with a link to the invoice's hosted page where they can pay with another card. Paying there with a new card also moves the subscription onto it.

**3. Bouclay retries on a schedule**

By default it retries 1, 3, 7 and 14 days after each attempt: 5 charge attempts over 25 days in all.

**4. Access is suspended if it stays unpaid**

By default, 7 days after the invoice was due the subscription is suspended: paused with `pauseReason: payment_overdue`, so the customer loses access. They are warned 3 days before. The invoice stays open, and paying it restores access on its own.

**5. When the retries run out**

Bouclay does what you chose as the final step (below).

When any attempt succeeds, the subscription goes back to `active`, the customer gets a receipt, and you get `subscription.updated` and `invoice.updated`.

## Choose your settings

Under **Billing settings → Failed payments** you can change:

* **The retry schedule:** up to 6 retries, each 0 to 30 days after the one before.
* **Suspending access while an invoice is overdue:** on or off, and after how many days.
* **The final step when the retries run out:**

| Final step | What happens |
| - | - |
| **Suspend until the invoice is paid** (default) | The customer loses access and the invoice stays open. Paying it restores access automatically. |
| **Cancel the subscription and write off the invoice** | The subscription ends. The invoice is marked uncollectible, so the customer no longer owes it. |
| **Pause the subscription and write off the invoice** | The subscription pauses until you resume it. The invoice is marked uncollectible. |
| **Leave the invoice open** | Nothing changes: the customer keeps access and the invoice stays open until it is paid or you close it. |

## Manual collection

For subscriptions paid by invoice (`collectionMode: manual`) nothing is charged, so there is nothing to retry. Instead the invoice turns the subscription `past_due` a day after it is due, the customer gets reminders, and suspension and the final step follow the same settings, counted from the due date.

## When the outcome is unknown

Sometimes a gateway doesn't say straight away whether a charge went through. The payment is then `processing`. Bouclay never charges again while one is processing: it asks the gateway for the outcome first, since the customer may already have paid. Retries wait until it is known.

## Doing it by hand

* `POST /subscriptions/{id}/retry-payment` charges the saved card for the oldest overdue invoice now, for example right after the customer tells you they topped up.
* `POST /invoices/{id}/payments` records a payment made outside the gateway, such as a bank transfer.
* `POST /invoices/{id}/mark-uncollectible` or `POST /invoices/{id}/void` writes the debt off. A `past_due` subscription becomes `active` again, and a suspended one becomes an ordinary pause for you to resume or cancel. See [Invoices](https://docs.bouclay.com/billing/invoices.md#writing-off-and-voiding).

## What your app should do

Gate access on [entitlements](https://docs.bouclay.com/integrate/entitlements.md), and you don't need any dunning logic of your own: `past_due` still grants access, and a suspension removes it. If you want to show a banner such as "Your last payment failed", watch for `subscription.updated` with `status: past_due`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.