Dunning (overdue invoice retries)

​

Overview

​

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

​

Final actions

​

Assigning a policy to a subscription

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

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

​

Checking dunning status on an invoice

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

​

Manually retrying or stopping

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

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

​

Webhooks

​

Co-existence with plan overdueAction

• 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