Process dunning

When a payment against an open invoice fails, Paylera enters dunning: a configured sequence of retries with backoff, optional customer-facing emails, and an explicit terminal step (cancel, mark uncollectible, or hand off).

The default policy

Out of the box, every tenant has a “smart retries” policy:

Attempt	Delay after previous
1	Immediate (the original capture)
2	3 days
3	5 days
4	7 days
Final	After 21 days, the subscription transitions to `canceled` and the invoice is marked `uncollectible`.

Each attempt sends an email to the customer (if you’ve enabled email delivery in Settings → Customer emails).

Configuring your policy

PATCH /v1/admin/dunning/policy
{
  "name": "default",
  "schedule": [
    { "attempt": 2, "after_days": 3, "send_email": true },
    { "attempt": 3, "after_days": 5, "send_email": true },
    { "attempt": 4, "after_days": 7, "send_email": false }
  ],
  "on_exhaustion": "cancel_subscription",
  "max_total_days": 21
}

on_exhaustion:

cancel_subscription (default) — sub → canceled, invoice → uncollectible.
pause_subscription — sub → paused; you decide what to do later.
mark_uncollectible_only — invoice → uncollectible, subscription stays past_due.
notify_only — emit dunning.exhausted; take no action.

max_total_days is a hard cap; once exceeded, exhaustion fires regardless of remaining schedule entries.

Per-plan overrides

Some plans warrant different policies (annual contracts deserve more patience than $9 monthly):

PATCH /v1/plans/enterprise-annual-usd
{
  "dunning_policy": "enterprise-grace"
}

The plan’s policy overrides the tenant default for any subscription on that plan.

Smart retries with provider hints

For each attempt, Paylera asks the payment provider whether the failure is retriable and on what timeline (e.g. Stripe Adaptive Acceptance). When the provider returns a hint, the configured after_days is used as a minimum — the provider’s recommended delay is honoured if it’s longer.

To force the configured schedule and ignore provider hints:

{ "use_provider_hints": false }

Default is true. Provider hints typically improve recovery rate by 8–15%.

Customer-facing emails

Enable in Settings → Customer emails. The templates Paylera ships cover:

Payment failed: notification with the failure reason and a link back to the customer portal to update the method.
Final notice: T-3 days before the dunning policy exhausts.
Subscription canceled (or paused, uncollectible): the terminal outcome.

To customise wording, override the templates per locale in the dashboard. To suppress all dunning emails (you’d rather send them from your own ESP), set send_email: false on every schedule entry.

What your app should do

Event	Recommended action
`subscription.past_due`	Show a banner. Don’t deprovision. Disable non-essential features (e.g. invites).
`subscription.dunning_attempt`	Update the banner with attempt number / next retry date.
`subscription.canceled` (after dunning exhausted)	Deprovision. Tag for win-back.

Manual intervention

To retry now (skip the schedule):

POST /v1/subscriptions/{id}/retry-payment
{ "payment_method_id": "pm_…" }

Optional payment_method_id overrides the configured method (useful when the customer just added a new card).

To skip the policy and exhaust immediately:

POST /v1/subscriptions/{id}/dunning/exhaust
{ "reason": "operator_decision" }

To put dunning on hold without changing the schedule (useful while you wait for the customer to call back):

POST /v1/subscriptions/{id}/dunning/pause
{ "until": "2026-05-12T00:00:00Z" }

Webhook events

Event	When
`subscription.past_due`	First failed attempt.
`subscription.dunning_attempt`	Each subsequent attempt.
`subscription.dunning_recovered`	A retry succeeded; the subscription is back to `active`.
`subscription.dunning_exhausted`	The policy ran out; `on_exhaustion` action follows.
`invoice.payment_failed`	Per individual failed attempt.
`invoice.marked_uncollectible`	Terminal write-off.