Advanced dunning

Orb’s Automated Dunning is a flexible, rule-based system designed to help you recover revenue from failed payments and overdue invoices. You can configure multi-step schedules to automatically retry payments, send customized email reminders, and manage the entire collections process.

​

How It Works

The dunning process is triggered automatically and follows a schedule you define.

1. When an invoice payment fails or the invoice becomes overdue, Orb’s system checks for a matching Dunning Rule.
2. If a matching rule is found, Orb creates a Dunning Schedule for that specific invoice based on the rule’s associated template.
3. The schedule executes a series of steps at the specified times, which can include retrying the payment or sending an email.
4. The schedule runs until the invoice is paid (ending early) or until all steps have been completed (exhaustion).

​

Core Concepts

The dunning system is built on two key concepts: Rules and Schedules.

​

Dunning Rules

Dunning Rules determine which dunning schedule to apply to an invoice. Invoices are evaluated against your list of rules, and the first one that matches is used. Each rule has a priority to determine the order of evaluation. You can define rules using a flexible set of criteria:

• Plan IDs: Apply the rule only to invoices associated with specific plans.
• Payment Method Types: Apply the rule based on the payment method used (e.g., credit card, ACH).
• Excluded Customer IDs: Prevent the rule from applying to certain customers.
• One-Off Invoices: Specify whether the rule should apply to invoices not associated with a subscription.

​

Dunning Schedules

A Dunning Schedule is a template composed of one or more steps that define the timeline of actions to take on an overdue invoice. Each step in the schedule consists of:

• Offset: The number of days from the invoice’s due date to perform the action. This can be a positive number (after the due date) or a negative number to send proactive reminders before the due date.
• Actions: The specific actions to take at that step, such as retrying the payment or sending an email.

​

The Dunning Lifecycle

A dunning schedule can be created at different points in an invoice’s lifecycle.

​

When Schedules are Created

Dunning rules are evaluated to create a schedule at these key moments:

1. When an invoice is finalized: Rules are evaluated based on all criteria except the payment method type.
2. When an auto-collection payment fails: Rules are evaluated again, this time including the payment method type that was used for the failed attempt. A new schedule will not be created if one already exists for the invoice from the finalization step.
3. When a customer’s payment method is updated to a different type that also fails: If a customer switches from one failing payment method type to another (e.g., from a failed credit card to a failed ACH), the existing dunning schedule is canceled and a new one is created based on the new payment method.

Note: A dunning schedule is not created if a customer manually tries to pay an invoice through the customer portal and that payment fails.

​

Managing Active Schedules

You can programmatically manage an in-progress dunning schedule:

• Pause: Pausing a schedule will delete all future scheduled steps.
• Resume: Resuming a schedule immediately executes the next step in the sequence. The remaining steps are then recalculated based on the current date and the latest version of the schedule template.
• Cancel: This action permanently stops the dunning schedule and marks all remaining steps as canceled.
• Automatic Termination: A schedule automatically ends if the invoice is marked as paid or voided.
• Exhaustion: If all steps in the schedule are completed and the invoice remains unpaid, the schedule is considered exhausted.

​

Available Actions

​

Email Notifications

You can configure dunning steps to send branded emails using pre-defined templates. The available templates are:

• payment_due_soon
• payment_past_due
• payment_retry_failed
• final_notice

​

Payment Retries

When a retry_payment action is executed, Orb attempts to charge the customer’s existing payment method on file.

• If successful, the customer receives a standard payment receipt email.
• If it fails, an email is sent to the customer using the template specified in that dunning step.

​

Webhooks

You can subscribe to webhooks to monitor dunning events in real-time. Available Webhooks:

• invoice.dunning_schedule_created: Fired when a dunning schedule is created for an invoice.
• invoice.dunning_schedule_ended: Fired when a schedule ends, either due to successful payment or exhaustion.
• invoice.dunning_schedule_reset: Fired when an old schedule is canceled and a new one is created due to a change in payment method type.
• invoice.dunning_schedule_step_executed: Fired each time a step’s actions (e.g., email sent, payment retried) are executed.

​

Prerequisites

To enable dunning, you must have the following two settings turned on in your Invoice settings:

1. Automatically send Orb invoice emails
2. Retry payments automatically

​

Testing Your Dunning Configuration

You can test your dunning rules and schedules in Test mode.

• Environment Parity: Dunning configurations for Test mode and Live mode are completely separate. You will need to create your rules and schedules in both environments.
• Email Behavior: In Test mode, dunning emails are not sent automatically for scheduled steps. Payment retries will still occur as scheduled.
• Fast Forwarding: To help with testing, a “Fast forward to next step” button appears on invoices in Test mode once they are past due. Clicking this button will:
  • Immediately process the next scheduled dunning step.
  • Trigger an email for the action, since it’s considered a manual event.
  • Note: This only affects the timing of the current step; all subsequent steps remain on their original schedule.