Skip to main content
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:

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

​
What your app should do

Gate access on entitlements, 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.