How Dunning Works

When a payment fails in BillHive, the dunning recovery workflow is triggered automatically. This page explains each phase of the recovery process in detail.

Decline Classification

The first step is classifying the payment failure as a soft decline or hard decline. This determines the retry strategy.

If the failure reason is unknown, it defaults to soft decline to maximize recovery chances.

Phase 1: Soft Retry (Day 0)

For soft declines only. The system attempts up to 3 immediate retries with 30-minute intervals between each attempt.

Payment Fails (soft decline)
    → Retry #1 (immediate)
    → Wait 30 minutes
    → Retry #2
    → Wait 30 minutes
    → Retry #3
    → If still failed → proceed to Phase 2

This phase recovers payments where the failure was truly temporary (e.g., a brief bank outage or a momentary insufficient balance).

Phase 2: Smart Retry (Day 1–7)

Scheduled retries with customer communication. The system performs 4 retry attempts over 7 days while sending escalating emails.

Before each retry, the system checks whether the customer has already made a payment (e.g., via a self-serve payment update link). If the invoice is already paid, the dunning process ends immediately.

Payment Update Link

On Day 0, a self-serve payment update link is generated and included in all dunning emails. This link allows customers to:

• Update their credit card or payment method
• Make an immediate payment for the overdue invoice
• View their outstanding balance

The link format is: https://app.billhive.com/update-payment/{tenantId}/{subscriptionId}

Phase 3: Grace Period (Day 7–14)

The subscription remains active but is flagged. During this phase:

• Day 10: Premium features may be restricted; “Account Restricted” email sent
• Day 14: “Final Notice” email sent — “Your subscription will be cancelled”
• Payment status is checked at each milestone

The customer can self-serve payment at any time during the grace period. When a payment method is updated, an immediate retry is triggered.

Feature Restriction

During the grace period, the system can restrict premium features while keeping basic access available. This creates urgency without fully disrupting the customer’s workflow.

Phase 4: Escalation (Day 14–21)

If payment is still not recovered:

• Subscription is paused or downgraded
• “Account Suspended” notification sent
• High-value accounts (amount due > configurable threshold) are flagged for manual review by the customer success team
• 3 additional retry attempts at Day 14, 17, and 21
• Payment status checked before each retry

Manual Review

High-value accounts are escalated to manual review with a CRITICAL severity activity log entry. The CSM team can:

• Contact the customer directly
• Arrange alternative payment terms
• Extend the dunning period if needed

Phase 5: Hard Action (Day 21)

If all recovery attempts are exhausted:

1. Subscription cancelled — Status set to Cancelled
2. Invoice written off — Status set to Written Off (uncollectible)
3. Cancellation email sent — Includes a reactivation link for future recovery

An activity log entry is created with the full dunning history for audit purposes.

Phase 6: Win-Back (Day 30+)

9 days after cancellation (Day 30 from dunning start):

• Win-back email sent with a reactivation link
• Optional discount incentive to encourage return
• Reactivation link remains valid for 90 days
• Recovery rate is tracked for ROI reporting

Recovery at Any Stage

At every retry and status check point throughout all 6 phases, if the system detects that the payment has been made (either through automated retry or customer self-service), the dunning process ends with status EndEvent_Recovered. The subscription is restored to its previous active state.

Dunning Timeline Summary

Day 0:  Payment fails → Classify decline → Soft retries (3x, 30min) → "Payment Failed" email
Day 1:  Smart retry #1
Day 3:  Smart retry #2 → "Reminder" email
Day 5:  Smart retry #3 → "Urgent" email + SMS
Day 7:  Smart retry #4 → "Final Warning" email
Day 10: Restrict features → "Account Restricted" email
Day 14: "Final Notice" email → Escalate → Pause subscription → Retry
Day 17: Retry
Day 21: Final retry → Cancel subscription → Write off invoice → "Cancellation" email
Day 30: Win-back email with reactivation link

Activity Logging

Every dunning action is recorded in the activity log with:

• Event type (e.g., Payment Failed, Payment Retry, Subscription Cancelled)
• Severity (INFO for retries, WARNING for escalation, CRITICAL for cancellation and high-value flagging)
• Metadata (subscription ID, invoice ID, amount, currency, retry count)
• Related entities (links to subscription, invoice, and payment records)

Notification Events

The following notification events are triggered during dunning: