Billing Dunning Management

Overview

The MECLABS AI platform implements a comprehensive dunning management system to recover failed subscription payments while maintaining positive customer relationships. The system uses Stripe's Smart Retries combined with custom communication workflows to maximize payment recovery rates while minimizing involuntary churn.

Core Components

Payment Retry Strategy

Multi-tiered retry approach optimized for B2B SaaS recovery patterns:

1. Smart Retries (Stripe-managed):

   • Machine learning-based optimal retry timing
   • Automatic retry for 4 attempts over 28 days
   • Network-level decline handling
   • Card updater integration for expired cards

2. Custom Retry Schedule (for manual intervention):

   • Day 0: Initial failure (immediate notification)
   • Day 3: First retry attempt
   • Day 7: Second retry with escalation
   • Day 14: Third retry with suspension warning
   • Day 28: Final attempt before cancellation

Communication Workflows

Email Notification Sequence

Progressive messaging aligned with retry attempts:

Day	Email Type	Subject Line	Key Message	Call-to-Action
0	Payment Failed	"Action Required: Payment Failed for MECLABS AI"	Friendly notification of failed payment	Update payment method
3	First Reminder	"Reminder: Update Your Payment Information"	Emphasize continued access at risk	One-click payment update
7	Urgency	"Important: Your MECLABS AI Access Will Be Limited"	Features being restricted, credit consumption halted	Update now to restore access
14	Final Warning	"Final Notice: Account Suspension in 14 Days"	Clear suspension timeline, data preservation notice	Urgent payment update
28	Cancellation	"MECLABS AI Subscription Cancelled"	Account suspended, 30-day data retention, reactivation options	Contact support or resubscribe

In-App Notifications

Contextual alerts within the platform:

• Banner notifications: Persistent top-bar alert for payment issues
• Feature restrictions: Gradual limitation warnings before suspension
• Credit warnings: Alert when credits won't renew due to payment failure
• Partner notifications: Alert resellers about commission impact

Account Status Management

Grace Period (Days 0-7)

• Full platform access maintained
• Credit consumption continues (with warnings)
• All features remain active
• Customer Kit deployments operational
• Email notifications only

Restricted Period (Days 8-14)

• Read-only access to existing agents
• No new agent creation or modification
• Credit consumption blocked for new operations
• Customer Kits remain active (separate billing)
• Prominent in-app warnings
• Support ticket auto-created

Suspension Period (Days 15-28)

• Platform access limited to billing pages
• Agent delivery systems (ADS) enter read-only mode
• API access restricted to GET operations
• Customer Kit access maintained (if separately paid)
• Daily email reminders
• Account marked "past_due" in Stripe

Cancellation (Day 29+)

• Subscription terminated
• 30-day data retention period begins
• Export tools remain accessible
• Customer Kits transferred to standalone billing
• Reactivation requires new subscription
• Partner commissions suspended

Technical Implementation

Stripe Webhook Events

Key events for dunning management:

// Payment failure events
'invoice.payment_failed': {
  action: 'initiateDunning',
  triggers: ['emailNotification', 'updateAccountStatus', 'logFailure']
}

// Retry events
'invoice.payment_action_required': {
  action: 'requestAuthentication',
  triggers: ['3dsChallenge', 'customerNotification']
}

// Recovery events
'invoice.payment_succeeded': {
  action: 'clearDunning',
  triggers: ['restoreAccess', 'resetStatus', 'confirmationEmail']
}

// Subscription status changes
'customer.subscription.updated': {
  statuses: ['past_due', 'unpaid', 'canceled'],
  actions: ['syncAccountStatus', 'updateFeatureFlags']
}

Database Schema Extensions

// Organization dunning state
{
  dunningStatus: {
    active: boolean,
    startDate: Timestamp,
    lastRetryDate: Timestamp,
    retryCount: number,
    scheduledSuspension: Timestamp,
    failureReason: string, // 'card_declined', 'insufficient_funds', etc.
    recoveryAttempts: [{
      date: Timestamp,
      method: string, // 'auto_retry', 'manual_update', 'support_intervention'
      result: string,
      amount: number
    }]
  }
}

// User notification preferences
{
  billingNotifications: {
    emailEnabled: boolean,
    smsEnabled: boolean, // Future enhancement
    webhookUrl?: string, // For enterprise accounts
    ccEmails: string[], // Additional notification recipients
    preferredChannel: 'email' | 'in_app' | 'both'
  }
}

Credit System Integration

Credit handling during dunning:

1. Grace Period: Credits continue to deplete normally with warning overlays
2. Restricted Period: No new credit allocations; existing credits remain usable
3. Suspension: Credit consumption blocked; balance preserved
4. Cancellation: Credits expire per standard 90-day policy

Partner Program Impact

Commission and partner account handling:

• Active dunning: Commissions accrue but payment held
• Successful recovery: Held commissions released in next cycle
• Cancellation: Commissions stopped; partner notified
• Customer Kits: Separately billed; unaffected by organization dunning

Recovery Optimization

Payment Method Management

Proactive payment failure prevention:

1. Card expiration warnings: 30-day advance notice
2. Backup payment methods: Optional secondary card storage
3. Payment method updater: Automatic card detail refresh via Stripe
4. Corporate billing options: Net-30 terms for qualifying accounts

Win-back Campaigns

Re-engagement strategies for cancelled accounts:

• 30-day offer: 20% discount for reactivation within 30 days
• Data export: One-click export before permanent deletion
• Downgrade options: Suggest lower tier instead of cancellation
• Partner intervention: Alert reseller partners for high-value accounts

Analytics & Monitoring

Key metrics tracked:

Metric	Target	Measurement
Recovery Rate	>70%	Successful payments / total failures
Time to Recovery	<7 days	Average days from failure to success
Involuntary Churn	<2%	Dunning cancellations / total subscribers
Email Open Rate	>60%	Dunning email opens / sends
Self-service Recovery	>80%	Portal updates / total recoveries

Customer Experience Optimization

Self-Service Portal

Billing management features:

• Payment method update: One-click card update
• Retry payment: Manual retry trigger
• Invoice history: Complete payment record access
• Subscription pause: Temporary suspension option (Scale tier only)
• Payment schedule: View upcoming charges

Support Escalation

Tiered support based on account value:

1. Build Tier: Email support, 48-hour response
2. Sell Tier: Priority email, 24-hour response
3. Scale Tier: Dedicated success manager notification
4. Enterprise: Phone escalation, executive involvement

Localization

Region-specific considerations:

• Payment methods: Regional alternatives (SEPA, ACH)
• Time zones: Retry attempts during business hours
• Languages: Localized dunning emails (future enhancement)
• Regulations: GDPR-compliant data retention

Compliance & Legal

Data Retention

Post-cancellation data handling:

• 30-day grace: Full data preservation
• 31-90 days: Archived state, restorable on resubscription
• 90+ days: Permanent deletion, GDPR-compliant
• Export rights: Always available during retention period

Terms of Service Alignment

Dunning process compliance:

• Clear suspension timeline in Terms of Service
• Right to restrict access for non-payment
• Data preservation commitments
• Reactivation terms and conditions

Audit Requirements

Documentation maintained:

• All payment attempts logged
• Customer communications archived
• Status changes timestamped
• Support interventions recorded

Implementation Roadmap

Phase 1: Foundation (Current)

• Basic Stripe retry logic
• Email notifications
• Manual support intervention

Phase 2: Automation (Q1 2025)

• Progressive account restrictions
• In-app notifications
• Self-service payment update

Phase 3: Optimization (Q2 2025)

• Machine learning retry timing
• Segmented communication flows
• Partner program integration

Phase 4: Advanced (Q3 2025)

• SMS notifications
• Regional payment methods
• Predictive churn prevention