Skip to content

feat: Build automated dunning management with configurable retry strategies #791

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
agenes01 wants to merge 3 commits into
base: main
Choose a base branch
from
Open

feat: Build automated dunning management with configurable retry strategies #791

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
e6a068d
feat: Build automated dunning management with configurable retry stra…
Jul 24, 2026
ce7bb84
Merge branch 'main' into fix-automated-dunning-retry
agenes01 Jul 25, 2026
1031b17
Merge branch 'main' into fix-automated-dunning-retry
agenes01 Jul 26, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
102 changes: 86 additions & 16 deletions backend/services/billing/dunningService.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,8 +6,11 @@ import type {
DunningEntry,
DunningStage,
DunningStageConfig,
FailureReason,
RetryStrategy
} from '../../../src/types/dunning';
import { DEFAULT_DUNNING_STAGES, DUNNING_TEMPLATES } from '../../../src/types/dunning';
import type { IDunningService } from './interfaces';

const ONE_HOUR_MS = 3_600_000;
const ONE_DAY_MS = 86_400_000;
Expand Down Expand Up @@ -72,20 +75,38 @@ export class DunningService {

configurePlan(planId: string, config: Partial<DunningConfiguration>): DunningConfiguration {
const existing = this.configurations.get(planId);

const defaultStrategy: RetryStrategy = config.defaultStrategy ?? existing?.defaultStrategy ?? {
stages: DEFAULT_DUNNING_STAGES,
maxRetries: 3,
retryIntervalHours: 1,
warnAfterFailures: 3,
suspendAfterDays: 3,
cancelAfterDays: 7,
communicationChannels: ['email', 'push'],
};

const merged: DunningConfiguration = {
planId,
stages: config.stages ?? existing?.stages ?? DEFAULT_DUNNING_STAGES,
maxRetries: config.maxRetries ?? existing?.maxRetries ?? 3,
retryIntervalHours: config.retryIntervalHours ?? existing?.retryIntervalHours ?? 1,
warnAfterFailures: config.warnAfterFailures ?? existing?.warnAfterFailures ?? 3,
suspendAfterDays: config.suspendAfterDays ?? existing?.suspendAfterDays ?? 3,
cancelAfterDays: config.cancelAfterDays ?? existing?.cancelAfterDays ?? 7,
communicationChannels: config.communicationChannels ?? existing?.communicationChannels ?? ['email', 'push'],
defaultStrategy,
strategies: config.strategies ?? existing?.strategies ?? {},
abTestConfig: config.abTestConfig ?? existing?.abTestConfig,
};

this.configurations.set(planId, merged);
return merged;
}

configureABTest(planId: string, enabled: boolean, variants: Array<{ id: string; weight: number; strategy: RetryStrategy }>): void {
const config = this.configurations.get(planId);
if (config) {
config.abTestConfig = { enabled, variants };
this.configurations.set(planId, config);
} else {
this.configurePlan(planId, { abTestConfig: { enabled, variants } });
}
}

getConfiguration(planId: string): DunningConfiguration | undefined {
return this.configurations.get(planId);
}
Expand Down Expand Up @@ -128,14 +149,30 @@ export class DunningService {
subscriberId: string,
merchantId: string,
planId: string,
failureReason: FailureReason = 'default'
): DunningEntry {
const existing = this.entries.get(subscriptionId);
if (existing) {
return existing;
}

const config = this.configurations.get(planId);
const firstStage = config?.stages[0] ?? DEFAULT_DUNNING_STAGES[0];
let abTestVariant: string | undefined;
if (config?.abTestConfig?.enabled && config.abTestConfig.variants.length > 0) {
// Pick variant randomly based on weight
const totalWeight = config.abTestConfig.variants.reduce((sum, v) => sum + v.weight, 0);
let r = Math.random() * totalWeight;
for (const v of config.abTestConfig.variants) {
r -= v.weight;
if (r <= 0) {
abTestVariant = v.id;
break;
}
}
}

const strategy = this.getStrategy(planId, failureReason, abTestVariant);
const firstStage = strategy.stages[0] ?? DEFAULT_DUNNING_STAGES[0];
const now_ts = now();

const entry: DunningEntry = {
Expand All @@ -144,6 +181,8 @@ export class DunningService {
subscriberId,
merchantId,
planId,
failureReason,
abTestVariant,
currentStage: firstStage.stage,
failedAttempts: 0,
totalFailedCharges: 0,
Expand Down Expand Up @@ -201,8 +240,8 @@ export class DunningService {
if (shouldAdvanceStage() && config) {
const currentStageIndex = config.stages.findIndex((s) => s.stage === entry.currentStage);
const nextStageIndex = currentStageIndex + 1;
if (nextStageIndex < config.stages.length) {
const nextStage = config.stages[nextStageIndex];
if (nextStageIndex < strategy.stages.length) {
const nextStage = strategy.stages[nextStageIndex];
entry.currentStage = nextStage.stage;
entry.failedAttempts = 0;
entry.nextActionAt = now_ts + nextStage.delayHours * ONE_HOUR_MS;
Expand Down Expand Up @@ -233,8 +272,10 @@ export class DunningService {
});
}

entry.updatedAt = now();
this.recoveredEntries.push(entry);

this.entries.delete(subscriptionId);
this.communicationLog.delete(subscriptionId);
}

getDunningEntry(subscriptionId: string): DunningEntry | undefined {
Expand Down Expand Up @@ -262,8 +303,8 @@ export class DunningService {
const entry = this.entries.get(subscriptionId);
if (!entry) return null;

const config = this.configurations.get(entry.planId);
const stageConfig = config?.stages.find((s) => s.stage === entry.currentStage);
const strategy = this.getStrategy(entry.planId, entry.failureReason, entry.abTestVariant);
const stageConfig = strategy.stages.find((s) => s.stage === entry.currentStage);
entry.isPaused = false;
entry.nextActionAt = now() + (stageConfig?.delayHours ?? 24) * ONE_HOUR_MS;
entry.updatedAt = now();
Expand All @@ -275,8 +316,8 @@ export class DunningService {
const entry = this.entries.get(subscriptionId);
if (!entry) return null;

const config = this.configurations.get(entry.planId);
const stageConfig = config?.stages.find((s) => s.stage === stage);
const strategy = this.getStrategy(entry.planId, entry.failureReason, entry.abTestVariant);
const stageConfig = strategy.stages.find((s) => s.stage === stage);
entry.currentStage = stage;
entry.failedAttempts = 0;
entry.nextActionAt = now() + (stageConfig?.delayHours ?? 24) * ONE_HOUR_MS;
Expand Down Expand Up @@ -369,15 +410,23 @@ export class DunningService {

getAnalytics(merchantId?: string): DunningAnalytics {
const allEntries = this.listActiveDunning(merchantId);
const recovered = merchantId
? this.recoveredEntries.filter(e => e.merchantId === merchantId)
: this.recoveredEntries;

const stageBreakdown: Record<DunningStage, number> = {
retry: 0,
warn: 0,
suspend: 0,
cancel: 0,
};

let totalLost = 0;
for (const entry of allEntries) {
stageBreakdown[entry.currentStage] = (stageBreakdown[entry.currentStage] ?? 0) + 1;
if (entry.currentStage === 'cancel') {
totalLost++;
}
}

const retryAnalytics = this.getRetryAnalytics(merchantId);
Expand All @@ -399,7 +448,7 @@ export class DunningService {
}

private sendCommunication(entry: DunningEntry, stageConfig: DunningStageConfig): DunningCommunication {
const template = DUNNING_TEMPLATES.find((t) => t.id === stageConfig.templateId);
const template = this.templates.find((t) => t.id === stageConfig.templateId);
const comm: DunningCommunication = {
id: createId('dcom'),
stage: stageConfig.stage,
Expand Down Expand Up @@ -427,6 +476,27 @@ export class DunningService {
(e) => !e.isPaused && e.nextActionAt <= now_ts
);
}

addTemplate(template: DunningCommunicationTemplate): void {
if (!this.templates.find(t => t.id === template.id)) {
this.templates.push(template);
}
}

updateTemplate(id: string, template: Partial<DunningCommunicationTemplate>): void {
const index = this.templates.findIndex(t => t.id === id);
if (index !== -1) {
this.templates[index] = { ...this.templates[index], ...template };
}
}

removeTemplate(id: string): void {
this.templates = this.templates.filter(t => t.id !== id);
}

getTemplates(): DunningCommunicationTemplate[] {
return [...this.templates];
}
}

export const dunningService = new DunningService();
4 changes: 4 additions & 0 deletions backend/services/billing/interfaces.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,9 @@ import {
DunningStage,
DunningCommunication,
DunningAnalytics,
FailureReason,
DunningCommunicationTemplate,
RetryStrategy
} from '../../../src/types/dunning';
import {
TransactionRecord,
Expand Down Expand Up @@ -93,6 +96,7 @@ export interface ITaxService {

export interface IDunningService {
configurePlan(planId: string, config: Partial<DunningConfiguration>): DunningConfiguration;
configureABTest(planId: string, enabled: boolean, variants: Array<{ id: string; weight: number; strategy: RetryStrategy }>): void;
getConfiguration(planId: string): DunningConfiguration | undefined;
startDunning(subscriptionId: string, subscriberId: string, merchantId: string, planId: string): DunningEntry;
recordFailedCharge(subscriptionId: string, failureType?: string): DunningEntry | null;
Expand Down
63 changes: 50 additions & 13 deletions src/store/dunningStore.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,8 @@
DunningConfiguration,
DunningCommunication,
DEFAULT_DUNNING_STAGES,
FailureReason,
RetryStrategy,
} from '../types/dunning';

const STORAGE_KEY = 'subtrackr-dunning';
Expand Down Expand Up @@ -122,7 +124,8 @@
subscriptionId: string,
subscriberId: string,
merchantId: string,
planId?: string
planId?: string,
failureReason?: FailureReason
) => DunningEntry;
recordPaymentAttempt: (
subscriptionId: string,
Expand Down Expand Up @@ -157,8 +160,7 @@
clearError: () => void;
}

const DEFAULT_CONFIG: DunningConfiguration = {
planId: 'default',
const DEFAULT_STRATEGY: RetryStrategy = {
stages: DEFAULT_DUNNING_STAGES,
maxRetries: RETRY_SCHEDULE_DAYS.length,
retryIntervalHours: 24,
Expand All @@ -168,6 +170,27 @@
communicationChannels: ['email', 'push', 'in_app'],
};

const DEFAULT_CONFIG: DunningConfiguration = {
planId: 'default',
defaultStrategy: DEFAULT_STRATEGY,
strategies: {},
};

function getStrategy(
config: DunningConfiguration,
failureReason?: FailureReason,
abTestVariant?: string
): RetryStrategy {
if (config.abTestConfig?.enabled && abTestVariant) {
const variant = config.abTestConfig.variants.find((v) => v.id === abTestVariant);
if (variant) return variant.strategy;
}
if (failureReason && config.strategies[failureReason]) {
return config.strategies[failureReason]!;
}
return config.defaultStrategy;
}

export const useDunningStore = create<DunningState>()(
persist(
(set, get) => ({
Expand All @@ -178,12 +201,19 @@
isLoading: false,
error: null,

startDunning: (subscriptionId, subscriberId, merchantId, planId = 'default') => {
startDunning: (
subscriptionId,
subscriberId,
merchantId,
planId = 'default',
failureReason = 'default'
) => {
const existing = get().entries.find((e) => e.subscriptionId === subscriptionId);
if (existing) return existing;

const config = get().configurations[planId] ?? DEFAULT_CONFIG;
const firstStage = config.stages[0] ?? DEFAULT_DUNNING_STAGES[0];
const strategy = getStrategy(config, failureReason);
const firstStage = strategy.stages[0] ?? DEFAULT_DUNNING_STAGES[0];
const ts = now();

const entry: DunningEntry = {
Expand All @@ -192,6 +222,7 @@
subscriberId,
merchantId,
planId,
failureReason,
currentStage: firstStage.stage,
failedAttempts: 0,
totalFailedCharges: 0,
Expand Down Expand Up @@ -233,10 +264,13 @@
return null;
}

const newFailureReason = failureReason ?? entry.failureReason;

Check failure on line 267 in src/store/dunningStore.ts

View workflow job for this annotation

GitHub Actions / Type Check 

Cannot find name 'failureReason'. Did you mean 'newFailureReason'?
const config = get().configurations[entry.planId] ?? DEFAULT_CONFIG;
const strategy = getStrategy(config, newFailureReason, entry.abTestVariant);
const ts = now();
const stageIdx = config.stages.findIndex((s) => s.stage === entry.currentStage);
const stageConfig = config.stages[stageIdx];

const stageIdx = strategy.stages.findIndex((s) => s.stage === entry.currentStage);
const stageConfig = strategy.stages[stageIdx];
const newFailedAttempts = entry.failedAttempts + 1;

get().retryHistory.push({
Expand All @@ -249,7 +283,7 @@
});

let nextStage: DunningStage = entry.currentStage;
let nextDelay = config.retryIntervalHours * ONE_HOUR_MS;
let nextDelay = strategy.retryIntervalHours * ONE_HOUR_MS;
const newComm: DunningCommunication = {
id: createId('dcom'),
stage: entry.currentStage,
Expand All @@ -262,18 +296,18 @@

if (newFailedAttempts >= schedule.maxRetries) {
const nextIdx = stageIdx + 1;
if (nextIdx < config.stages.length) {
nextStage = config.stages[nextIdx].stage;
nextDelay = config.stages[nextIdx].delayHours * ONE_HOUR_MS;
if (nextIdx < strategy.stages.length) {
nextStage = strategy.stages[nextIdx].stage;
nextDelay = strategy.stages[nextIdx].delayHours * ONE_HOUR_MS;
} else {
nextStage = 'cancel';
nextDelay = 24 * ONE_HOUR_MS;
}
} else if (stageConfig && newFailedAttempts >= stageConfig.maxAttempts) {
const nextIdx = stageIdx + 1;
if (nextIdx < config.stages.length) {

Check failure on line 308 in src/store/dunningStore.ts

View workflow job for this annotation

GitHub Actions / Type Check 

Property 'stages' does not exist on type 'DunningConfiguration'.
nextStage = config.stages[nextIdx].stage;

Check failure on line 309 in src/store/dunningStore.ts

View workflow job for this annotation

GitHub Actions / Type Check 

Property 'stages' does not exist on type 'DunningConfiguration'.
nextDelay = config.stages[nextIdx].delayHours * ONE_HOUR_MS;

Check failure on line 310 in src/store/dunningStore.ts

View workflow job for this annotation

GitHub Actions / Type Check 

Property 'stages' does not exist on type 'DunningConfiguration'.
} else {
nextStage = 'cancel';
nextDelay = 24 * ONE_HOUR_MS;
Expand All @@ -291,6 +325,7 @@
e.subscriptionId === subscriptionId
? {
...e,
failureReason: newFailureReason,
currentStage: nextStage,
failedAttempts: nextStage !== entry.currentStage ? 0 : newFailedAttempts,
totalFailedCharges: e.totalFailedCharges + 1,
Expand Down Expand Up @@ -357,7 +392,8 @@
const entry = get().entries.find((e) => e.subscriptionId === subscriptionId);
if (!entry) return;
const config = get().configurations[entry.planId] ?? DEFAULT_CONFIG;
const stageConfig = config.stages.find((s) => s.stage === entry.currentStage);
const strategy = getStrategy(config, entry.failureReason, entry.abTestVariant);
const stageConfig = strategy.stages.find((s) => s.stage === entry.currentStage);
const delay = (stageConfig?.delayHours ?? 24) * ONE_HOUR_MS;

set((s) => ({
Expand All @@ -373,7 +409,8 @@
const entry = get().entries.find((e) => e.subscriptionId === subscriptionId);
if (!entry) return;
const config = get().configurations[entry.planId] ?? DEFAULT_CONFIG;
const stageConfig = config.stages.find((s) => s.stage === stage);
const strategy = getStrategy(config, entry.failureReason, entry.abTestVariant);
const stageConfig = strategy.stages.find((s) => s.stage === stage);
const delay = (stageConfig?.delayHours ?? 24) * ONE_HOUR_MS;

set((s) => ({
Expand Down
7 changes: 6 additions & 1 deletion src/store/subscriptionStore.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -742,7 +742,7 @@
return (get().pauseRecords || []).filter((p) => p.subscriptionId === subscriptionId);
},

calculatePauseAnalytics: (subscriptionId?: string) => {

Check failure on line 745 in src/store/subscriptionStore.ts

View workflow job for this annotation

GitHub Actions / Type Check 

Type '(subscriptionId?: string) => void' is not assignable to type '(subscriptionId?: string | undefined) => PauseAnalytics'.
const records = subscriptionId
? (get().pauseRecords || []).filter((p) => p.subscriptionId === subscriptionId)
: get().pauseRecords || [];
Expand Down Expand Up @@ -997,7 +997,11 @@
}
},

recordBillingOutcome: async (id: string, outcome: 'success' | 'failed') => {
recordBillingOutcome: async (
id: string,
outcome: 'success' | 'failed',
failureReason?: FailureReason

Check failure on line 1003 in src/store/subscriptionStore.ts

View workflow job for this annotation

GitHub Actions / Type Check 

Cannot find name 'FailureReason'.
) => {
const sub = get().subscriptions.find((s) => s.id === id);
if (!sub) return;

Expand All @@ -1010,6 +1014,7 @@

dunningEntries[id] = {
failedAttempts: attempt,
failureReason: failureReason || 'default',
lastFailureAt: new Date().toISOString(),
currentStage:
attempt <= 3 ? 'retry' : attempt <= 5 ? 'warn' : attempt <= 7 ? 'suspend' : 'cancel',
Expand Down
Loading
Loading