Billing Automation

Overview

Build automated billing workflows covering invoice generation, PDF rendering, payment processing, dunning (payment failure handling), and financial reporting. Handles proration, usage-based billing, multi-currency support, tax calculation, discounts, and professional invoice document generation.

Instructions

1. Define the Billing Model

• Flat subscription: Fixed price per period (monthly/annual)
• Usage-based: Metered billing (API calls, storage, compute hours)
• Tiered: Volume-based pricing with breakpoints
• Hybrid: Base subscription + usage overage
• Per-seat: Price per active user

2. Design the Invoice Data Model

invoices (
  id, customer_id, invoice_number, status,
  billing_period_start, billing_period_end,
  subtotal, tax_amount, total, currency,
  due_date, paid_at, created_at
)
invoice_line_items (
  id, invoice_id, description, quantity, unit_price,
  amount, metadata_json
)
payments (
  id, invoice_id, amount, currency, method,
  processor_ref, status, paid_at
)

3. Invoice Generation Pipeline

For each billing cycle:
  1. Aggregate usage events for the billing period
  2. Apply pricing rules (tiers, discounts, proration)
  3. Calculate taxes based on customer location
  4. Generate invoice record with line items
  5. Render PDF with company branding
  6. Send via email and store in customer portal
  7. Initiate payment collection (auto-charge or payment link)
  8. Handle payment success/failure with appropriate follow-up

4. Generate Invoice PDFs

Gather required information and render professional documents:

• Sender: Company name, address, email, phone, logo, tax ID
• Recipient: Client name, address, contact information
• Invoice number: Auto-generate sequential (INV-YYYY-NNN) or use custom scheme
• Line items: Description, quantity, unit price, amount
• Calculations: Subtotal, discount, tax (VAT/GST/sales tax), total
• Payment terms: Net 30/60, accepted methods, bank details

from decimal import Decimal, ROUND_HALF_UP

CENT = Decimal("0.01")

def _money(value):
    return value.quantize(CENT, rounding=ROUND_HALF_UP)

def calculate_invoice(items, tax_rate="0", discount="0"):
    """items: [{"quantity": 12, "unit_price": "29.00"}]; tax_rate and discount are percentages."""
    subtotal = sum(Decimal(str(i["quantity"])) * Decimal(i["unit_price"]) for i in items)
    discount_amount = _money(subtotal * Decimal(discount) / 100)
    taxable_amount = subtotal - discount_amount          # tax is charged after the discount
    tax_amount = _money(taxable_amount * Decimal(tax_rate) / 100)
    total = taxable_amount + tax_amount
    return {
        "subtotal": _money(subtotal),
        "discount": discount_amount,
        "tax": tax_amount,
        "total": _money(total),
    }

# calculate_invoice([{"quantity": 1, "unit_price": "3500.00"},
#                    {"quantity": 1, "unit_price": "1200.00"},
#                    {"quantity": 12, "unit_price": "29.00"}], tax_rate="20", discount="10")
# -> subtotal 5048.00, discount 504.80, tax 908.64, total 5451.84

Use Decimal, not float: round() on floats uses banker's rounding and binary floats drift (0.1 + 0.2 is not 0.3). In JavaScript, keep amounts in integer cents or use a decimal library.

For PDF rendering, use reportlab (Python) or PDFKit (Node.js) with a clean layout: header with company info, invoice metadata, bill-to section, line items table, totals, and payment terms.

5. Handle Edge Cases

• Proration: Calculate partial charges for mid-cycle upgrades
• Credits: Apply account credits before charging payment method
• Disputes: Mark invoice as disputed, pause dunning
• Refunds: Generate credit notes linked to original invoice
• Currency: Store amounts in smallest unit (cents); display with proper formatting
• Tax: Integrate with tax service for multi-jurisdiction compliance

6. Dunning (Payment Failure) Workflow

Payment failed:
  Day 0: Retry payment, send "payment failed" email
  Day 3: Retry with updated payment method prompt
  Day 7: Final retry, warn about service suspension
  Day 14: Suspend service, send "account suspended" email
  Day 30: Cancel subscription, final notice

If you bill through Stripe, let Stripe run the retries where you can. Stripe Smart Retries picks retry times with its own model, and a custom retry schedule allows up to three retries, each a set number of days after the previous attempt. Your own schedule in code then covers only the emails, suspension and cancellation steps. Each failed attempt fires invoice.payment_failed, so use that event to drive the escalation stages.

Examples

Example 1: Usage-based invoice generation

User prompt: "Generate monthly invoices for our API platform. Tiered pricing: first 10,000 calls free, 10,001-100,000 at $0.001 each, 100,001+ at $0.0005 each."

calculateTieredPricing(totalCalls) {
  const items = [];
  if (totalCalls <= 10000) {
    items.push({ description: 'API calls (free tier)', quantity: totalCalls, unitPrice: 0, amount: 0 });
  } else if (totalCalls <= 100000) {
    items.push({ description: 'API calls (free tier)', quantity: 10000, unitPrice: 0, amount: 0 });
    const paid = totalCalls - 10000;
    items.push({ description: 'API calls (standard)', quantity: paid, unitPrice: 0.001, amount: paid * 0.001 });
  } else {
    items.push({ description: 'API calls (free tier)', quantity: 10000, unitPrice: 0, amount: 0 });
    items.push({ description: 'API calls (standard)', quantity: 90000, unitPrice: 0.001, amount: 90 });
    const bulk = totalCalls - 100000;
    items.push({ description: 'API calls (volume)', quantity: bulk, unitPrice: 0.0005, amount: bulk * 0.0005 });
  }
  return items;
}

Example 2: Freelance invoice with tax and discount

User prompt: "Invoice TechStart Ltd: website design $3,500, SEO setup $1,200, hosting 12 months at $29/mo. 20% VAT. 10% early payment discount. Currency EUR."

Output:

Invoice #INV-2025-002 | Currency: EUR

  Website Design          1 x EUR 3,500.00 = EUR 3,500.00
  SEO Setup               1 x EUR 1,200.00 = EUR 1,200.00
  Web Hosting (12 months) 12 x EUR 29.00   = EUR   348.00

  Subtotal:    EUR 5,048.00
  Discount:   -EUR   504.80
  VAT (20%):   EUR   908.64
  Total:       EUR 5,451.84

  Payment Terms: Net 30 — 10% early payment discount applied

Example 3: Dunning workflow with Stripe

User prompt: "Implement a dunning workflow for failed subscription payments using Stripe."

The agent generates a dunning service with webhook handlers for invoice.payment_failed, email templates for each escalation stage, and automatic subscription status management. Retry timing comes from Stripe's Smart Retries or a custom schedule of at most three retries, so the service does not retry on its own timer in parallel with Stripe.

Guidelines

• Always use idempotency keys for payment operations to prevent double charges
• Store monetary amounts as integers in smallest currency unit (cents, pence)
• Generate sequential invoice numbers with no gaps for tax compliance
• Keep an immutable audit log of all billing events
• Include legally required fields: company details, tax ID, payment terms, line items
• Calculate tax on the post-discount amount, not the subtotal
• Format currency with two decimal places and correct symbol
• Default payment terms to Net 30 unless specified otherwise
• Never delete invoices — void them with a credit note instead (Stripe allows deleting only draft invoices; finalized ones are voided)
• Implement webhook handlers for payment processor events rather than polling
• Test with edge cases: zero usage, credits, currency rounding, proration