Dunning

When a payment fails, QBill reminds the customer on a schedule you control, then applies a final action to the subscription. This guide covers the schedule, what each step does, and how to change it.

Why QBill never charges on its own

Mobile money with Wave works by request: the customer approves each payment themselves. QBill never charges the customer on its own. Every reminder therefore carries a payment link, and the customer decides when to pay.

The schedule

By default, reminders go out 1, 3 and 7 days after the failure, then the final action applies. You can change this:

  • up to 5 steps;
  • each step is a number of days between 1 and 60;
  • the days must be rising (for example 2, 5, 10, never 5, 2).

Each step

At each step QBill:

  1. emails the customer with the payment link of the invoice;
  2. sends your endpoints the invoice.dunning_retry event (its attempt field says which reminder it is, see Webhooks).

The customer can pay through the link at any time. With a test key, a Decline on the simulated checkout starts this schedule (see Test mode).

The final step

After the last reminder goes out unpaid, final_action decides what happens:

final_action Result Event
past_due (default) The subscription becomes past_due and is not renewed until its invoice is paid. subscription.past_due
cancel The subscription is cancelled. subscription.cancelled

Changing it

Needs a secret key (qb_test_sk_… here).

curl -X PATCH https://api.qbill.dev/v1/account/preferences \
  -H "x-api-key: qb_test_sk_…" \
  -H "content-type: application/json" \
  -d '{"dunning":{"schedule_days":[2,5,10],"final_action":"cancel"}}'

These settings belong to the whole account: they apply to live and sandbox subscriptions alike, so changing them from a test key changes live behaviour too.

The default is { "schedule_days": [1, 3, 7], "final_action": "past_due" }. Related: Invoices & payments for the payment link and resending an invoice.

← Invoices & paymentsUsage →