Turning accounts receivable into code: An automated dunning architecture.

The architectural problem: The manual gap in modern billing stacks

The deterministic credit control state machine: Modeling dunning in software

Database schema: Structuring AR state persistence

schema.prisma — prisma
enum InvoiceStatus {
  ISSUED
  OVERDUE
  IN_DUNNING
  SETTLED
  WRITTEN_OFF
  REFERRED_TO_LEGAL
}
​
enum DunningStage {
  DAY_7_DIGITAL_REMINDER
  DAY_14_PHYSICAL_BREAKER
  DAY_28_STATUTORY_NOTICE
  DAY_45_LETTER_BEFORE_ACTION
}
​
model Invoice {
  id                  String         @id @default(uuid())
  invoiceNumber       String         @unique
  customerId          String
  customer            Customer       @relation(fields: [customerId], references: [id])
  amount              Decimal        @db.Decimal(10, 2)
  balanceRemaining    Decimal        @db.Decimal(10, 2)
  dueDate             DateTime
  status              InvoiceStatus  @default(ISSUED)
  dunningStage        DunningStage?  
  statutoryInterest   Decimal        @default(0.00) @db.Decimal(10, 2)
  statutoryFee        Decimal        @default(0.00) @db.Decimal(10, 2)
  dunningEvents       DunningEvent[]
  createdAt           DateTime       @default(now())
  updatedAt           DateTime       @updatedAt
}
​
model DunningEvent {
  id                  String         @id @default(uuid())
  invoiceId           String
  invoice             Invoice        @relation(fields: [invoiceId], references: [id])
  stage               DunningStage
  channel             String         // 'EMAIL' | 'PHYSICAL_POST'
  letterApiId         String?        // Consignment ID from LetterAPI
  postageClass        String?        // 'first_class' | 'second_class'
  mailmarkBarcode     String?        
  dispatchedAt        DateTime?      
  deliveredAt         DateTime?      
  createdAt           DateTime       @default(now())
}

The dispatch pipeline: Event-driven worker implementation

dunningWorker.ts — typescript
import { Worker, Job } from 'bullmq';
import { LetterAPI } from '@letterapi/sdk';
import { prisma } from './prismaClient';
​
const letterapi = new LetterAPI(process.env.LETTERAPI_API_KEY!);
​
export const dunningWorker = new Worker('dunning-queue', async (job: Job) => {
  const { invoiceId, targetStage } = job.data;
  const invoice = await prisma.invoice.findUnique({
    where: { id: invoiceId },
    include: { customer: true }
  });
​
  if (!invoice || invoice.status === 'SETTLED') {
    return { skipped: true, reason: 'Invoice settled or not found' };
  }
​
  // Execute physical dispatch via LetterAPI
  const letter = await letterapi.letters.create({
    recipient: {
      name: invoice.customer.companyName,
      attention: 'Head of Accounts Payable',
      line1: invoice.customer.addressLine1,
      line2: invoice.customer.addressLine2 || undefined,
      city: invoice.customer.city,
      postcode: invoice.customer.postcode,
      country: 'GB'
    },
    pdfUrl: `https://billing.internal.co.uk/invoices/${invoice.id}/notice-${targetStage}.pdf`,
    postageClass: 'first_class',
    doubleSided: true,
    color: true,
    metadata: {
      invoiceId: invoice.id,
      invoiceNumber: invoice.invoiceNumber,
      stage: targetStage
    },
    idempotencyKey: `dunning-${invoice.id}-${targetStage}`
  });
​
  // Record dunning event in database
  await prisma.dunningEvent.create({
    data: {
      invoiceId: invoice.id,
      stage: targetStage,
      channel: 'PHYSICAL_POST',
      letterApiId: letter.id,
      postageClass: 'first_class',
      dispatchedAt: new Date()
    }
  });
​
  await prisma.invoice.update({
    where: { id: invoice.id },
    data: { dunningStage: targetStage }
  });
​
  return { success: true, consignmentId: letter.id };
});

Webhook ingestion: Real-time postal event reconciliation

letterApiWebhookHandler.ts — typescript
import express from 'express';
import { prisma } from './prismaClient';
​
const app = express();
​
app.post('/api/webhooks/letterapi', express.json(), async (req, res) => {
  const { type, data } = req.body;
​
  if (type === 'letter.dispatched') {
    await prisma.dunningEvent.updateMany({
      where: { letterApiId: data.id },
      data: {
        dispatchedAt: new Date(data.dispatchedAt),
        mailmarkBarcode: data.mailmarkBarcode
      }
    });
    console.log(`Letter ${data.id} in transit with Royal Mail.`);
  }
​
  if (type === 'letter.delivered') {
    await prisma.dunningEvent.updateMany({
      where: { letterApiId: data.id },
      data: { deliveredAt: new Date(data.deliveredAt) }
    });
    console.log(`Letter ${data.id} delivered. Evidentiary proof logged.`);
  }
​
  res.status(200).json({ received: true });
});

The three levels of architectural failure in credit control

Enter the guide: LetterAPI as code-addressable postal infrastructure

The 3-step action plan: Implementing automated AR architecture

The stakes: Fragile manual dunning vs. robust programmatic execution

Get started with LetterAPI today

The financial controller's audit dashboard: Visualizing automated dunning in real time

Handling edge cases: Address validation failures, PDF timeouts, and dead letter queues

Idempotency deep dive: Preventing duplicate printing across distributed systems

Accounting software integration patterns: Webhooks, polling, and event bridges for Xero and NetSuite

The event-driven financial ledger: Reconciling payments with Stripe, Xero, and Open Banking