seaworld008/billing-automation

Billing Automation

Master automated billing systems including recurring billing, invoice generation, dunning management, proration, and tax calculation.

When to Use This Skill

• Implementing SaaS subscription billing
• Automating invoice generation and delivery
• Managing failed payment recovery (dunning)
• Calculating prorated charges for plan changes
• Handling sales tax, VAT, and GST
• Processing usage-based billing
• Managing billing cycles and renewals

Core Concepts

1. Billing Cycles

Common Intervals:

• Monthly (most common for SaaS)
• Annual (discounted long-term)
• Quarterly
• Weekly
• Custom (usage-based, per-seat)

2. Subscription States

trial → active → past_due → canceled
              → paused → resumed

3. Dunning Management

Automated process to recover failed payments through:

• Retry schedules
• Customer notifications
• Grace periods
• Account restrictions

4. Proration

Adjusting charges when:

• Upgrading/downgrading mid-cycle
• Adding/removing seats
• Changing billing frequency

Quick Start

from billing import BillingEngine, Subscription

# Initialize billing engine
billing = BillingEngine()

# Create subscription
subscription = billing.create_subscription(
    customer_id="cus_123",
    plan_id="plan_pro_monthly",
    billing_cycle_anchor=datetime.now(),
    trial_days=14
)

# Process billing cycle
billing.process_billing_cycle(subscription.id)

Detailed patterns and worked examples

Detailed pattern documentation lives in references/details.md. Read that file when the navigation tier above is insufficient.

<!-- LOCAL-CURATION-SUPPLEMENT:START -->

Implementation Checklist

Before building or changing billing logic, capture:

• Product catalog: plan ids, prices, currency, billing interval, trial rules, and included usage.
• Customer lifecycle: signup, trial conversion, renewal, pause, resume, cancellation, and reactivation.
• Payment failure policy: retry cadence, email/SMS notices, grace period, account restrictions, and final cancellation behavior.
• Proration rules: upgrades, downgrades, seat changes, coupons, taxes, refunds, and invoice credits.
• Ledger model: immutable invoice records, payment attempts, adjustments, and audit metadata.
• Compliance constraints: tax invoices, receipts, PCI boundaries, refund approvals, and data-retention requirements.

Verification Scenarios

Test billing changes with concrete timelines:

1. Trial user converts to paid plan before trial end.
2. Monthly subscriber upgrades mid-cycle and receives prorated credit.
3. Payment fails three times, enters dunning, then recovers.
4. Annual customer cancels with service continuing through paid period.
5. Seat count changes immediately before renewal.

Record expected invoices, subscription state transitions, customer notifications, and ledger entries for each scenario. Do not ship billing automation with only happy-path tests.

Risk Controls

Billing changes need stronger safeguards than ordinary workflow automation:

• Use idempotency keys for invoice creation, payment attempts, webhook processing, and retry jobs.
• Store external payment processor ids separately from internal subscription ids.
• Treat webhooks as eventually consistent; never assume event order is guaranteed.
• Make retry jobs safe to run more than once.
• Keep a manual override path for support teams, but log who changed what and why.
• Separate preview calculations from committed ledger writes.
• Add alerts for abnormal retry volume, invoice creation failures, tax calculation errors, and webhook backlog.

User-facing Summary

When reporting billing automation work, include the business effect:

Changed:
Risk reduced:
Customer impact:
Accounting impact:
Tests run:
Open rollout concern:

This helps reviewers evaluate both code correctness and revenue operations risk.

<!-- LOCAL-CURATION-SUPPLEMENT:END -->