Dunning (overdue invoice retries)

Automatically chase overdue invoices with configurable retry schedules before taking a final action.

Overview

Dunning is the process of systematically reminding customers to pay overdue invoices. PayBridgeNP’s dunning engine lets you define retry intervals and a final action (cancel, pause, or write off) so your cash collection happens automatically without manual intervention.

How it works

1. An invoice is issued and becomes overdue (past its due_at date without being paid).
2. If a dunning policy is assigned to the subscription (or the merchant has a default policy), the dunning cycle starts.
3. At each interval, a reminder email is sent and a invoice.dunning_attempt webhook fires.
4. When all retries are exhausted, the configured finalAction is applied and an invoice.dunning_exhausted webhook fires.
5. If the customer pays at any point during the cycle, the cycle stops and an invoice.paid webhook fires.

Creating a dunning policy

const policy = await paybridge.dunning.createPolicy({
  name: "Standard 3-strike",
  retryIntervalsDays: [1, 3, 7],   // remind at +1d, +3d, +7d after overdue
  finalAction: "cancel",           // 'cancel' | 'pause' | 'mark_uncollectible'
  isDefault: true,                 // use for all subscriptions unless overridden
});

Retry intervals

retryIntervalsDays is an array of days since the invoice went overdue at which each reminder is sent.

Array	Behaviour
[1, 3, 7]	Remind on day 1, day 3, day 7. After day 7 exhausted → final action.
[2, 5]	Two reminders. Shorter grace period.
[1]	Single reminder, then final action the next day.

Final actions

Value	Effect
cancel	Subscription cancelled immediately when retries exhausted.
pause	Subscription paused. Customer can pay the invoice later to resume.
mark_uncollectible	Invoice marked uncollectible. Subscription is left in its current state.

Assigning a policy to a subscription

Leave the default policy for most cases. Override per-subscription when needed:

await paybridge.dunning.setSubscriptionPolicy(subscriptionId, policyId);

// Revert to merchant default:
await paybridge.dunning.setSubscriptionPolicy(subscriptionId, null);

Checking dunning status on an invoice

const status = await paybridge.dunning.getInvoiceStatus(invoiceId);
// {
//   dunningStatus: 'retrying',
//   dunningAttemptCount: 2,
//   nextDunningAt: '2026-04-25T00:00:00Z',
//   attempts: [...]
// }

Manually retrying or stopping

// Immediately trigger the next retry (useful for testing):
await paybridge.dunning.retryInvoiceNow(invoiceId);

// Stop all further retries for an invoice:
await paybridge.dunning.stopInvoice(invoiceId);

Webhooks

Event	Fired when
invoice.dunning_attempt	A reminder is sent (includes attempt_number and next_attempt_at).
invoice.dunning_exhausted	All retries used - final action applied. Includes final_action.
invoice.paid	Customer pays during the dunning cycle - cycle stops automatically.

Co-existence with plan overdueAction

Each billing plan has an overdueAction setting (keep_active, mark_past_due, pause, cancel). Dunning and overdueAction are complementary:

• If a subscription has a dunning policy, the policy governs collection.
• Recommendation: set the plan’s overdueAction to mark_past_due when using dunning, so the subscription remains accessible while reminders are in flight.

Dashboard

Manage dunning policies at Billing → Dunning in the dashboard. You can create multiple policies, set a default, and deactivate old ones.