Configure Dunning

BillHive provides a fully configurable dunning system that lets you control retry behavior, dunning duration, and final actions when payment recovery is exhausted. All settings are managed through the Dunning Settings page in the BillHive UI.

Dunning Settings Page

Access dunning configuration via Settings > Dunning in the BillHive dashboard. Changes apply to all new dunning processes started after the configuration is saved. Active dunning processes continue with the settings that were in effect when they started.

General Settings

Enable Dunning

A master toggle that enables or disables the automated dunning process for your tenant.

When disabled, failed payments will not trigger the dunning recovery workflow. Existing active dunning processes will continue to completion.

High-Value Threshold

Invoices with a due amount above this threshold are classified as high-value and escalated to manual review during the Escalation phase.

High-value accounts receive additional attention and are flagged for manual review before any final actions are taken.

Retry Configuration

Retry Schedule

The days, counted from the first failed payment, on which the payment is retried. The schedule decides everything about timing:

• Number of retries: one per day in the schedule.
• Dunning period: the final action is taken after the last day in the schedule.

Use recommended schedule fills in days 1, 3, 5, 7, 14, 17 and 21, based on payment industry practice. You can then add, remove or change days. The screen shows the result, for example “7 retries over 21 days”.

Soft retries are rapid retries attempted immediately after the initial failure (Day 0) to catch transient gateway errors. They run before the retry schedule begins.

Example

Earlier versions had separate Dunning Period, Max Retries and Retry Mode settings. They were removed because the schedule already decides all three; saving them through the API returns an error.

Final Actions

Configure what happens when the dunning period expires and all retries are exhausted.

Subscription Final Action

Invoice Final Action

Communication Schedule

Notification emails and SMS are sent at key points during the dunning process. The schedule adapts to your configured dunning period.

Note: When the dunning period is customized, the communication schedule is proportionally distributed across the configured period. Days shown above reflect the default 21-day dunning period.

Notification Templates

Dunning emails use the following business event types, which should be configured in the notification template settings:

Each template receives the following replacement data:

• subscription.productName, subscription.planName, subscription.subscriptionId
• account.name, account.email
• dunning.stage, dunning.paymentUpdateLink

Dunning Workflow (BPMN)

The dunning recovery process is implemented as a Camunda 7 BPMN workflow: dunning-recovery-workflow.bpmn. It is started automatically when any subscription enters dunning status.

The workflow now uses dynamic process variables loaded from the tenant’s dunning configuration at startup. This means changes to dunning settings are reflected in all newly started dunning processes without modifying the BPMN definition.

Input Variables

Service Task Topics

The workflow uses the following external task topics, each handled by a dedicated service:

Dunning Configuration API

Dunning settings are managed via the following REST API endpoints.

GET /dunning-config

Retrieve the current dunning configuration for the tenant.

Response:

{
  "enabled": true,
  "dunningPeriodDays": 21,
  "highValueThreshold": 10000,
  "retryMode": "smart",
  "customRetry": {
    "maxRetries": 10,
    "retryIntervals": [1, 3, 5, 7, 14, 17, 21],
    "softRetryCount": 3,
    "softRetryIntervalMinutes": 30
  },
  "finalActions": {
    "subscription": "cancel",
    "invoice": "write_off"
  }
}

PUT /dunning-config

Update the dunning configuration for the tenant.

Request body: Same schema as the GET response. All fields are optional — only include fields you want to update.

Validation rules:

Response: The full updated configuration object.

Related Topics

• How Dunning Works — Step-by-step flow explanation
• Dunning for Payment Types — Payment-type-specific behavior
• Pending Features — Planned enhancements