Overview

The Invoice Service manages the complete invoice lifecycle, from generation based on orders or contracts, through delivery to customers, to final payment. It ensures accurate billing and maintains invoice history.

Key Responsibilities

Invoice Generation

• Generate invoices from orders, contracts, or manual input
• Calculate line items, subtotals, taxes, and totals
• Apply discounts and promotional codes
• Generate sequential invoice numbers
• Support multiple invoice templates

Invoice Delivery

• Send invoices via email (PDF attachment)
• Generate customer portal links
• Support multiple delivery methods
• Track delivery status

Invoice Management

• Track invoice status (draft, sent, paid, overdue, voided)
• Handle partial payments
• Support invoice amendments (credit notes)
• Maintain invoice history and audit trail

Payment Tracking

• Listen for payment events
• Update invoice status when paid
• Handle partial payments
• Trigger overdue notifications

Invoice States

DRAFT → SENT → PENDING_PAYMENT → PAID
                      ↓
                   OVERDUE
                      ↓
               COLLECTIONS

DRAFT/SENT → VOIDED

Technical Details

Technology Stack:

• Runtime: Node.js 20
• Framework: Express.js
• Database: PostgreSQL (invoice data)
• PDF Generation: Puppeteer
• Email: SendGrid API
• Storage: S3 (PDF archives)

Invoice Numbering:

• Format: INV-YYYY-NNNNNN (e.g., INV-2025-000123)
• Sequential by fiscal year
• Gap-free sequence guaranteed

Performance:

• Invoice Generation: < 2s including PDF
• Email Delivery: < 5s
• Throughput: 1000 invoices/hour

Integration Points

• Order Service: Receives order completion events
• Payment Processing Service: Listens for payment events
• Ledger Service: Sends invoice events for AR recording
• AR Service: Coordinates collections
• Customer Service: Provides invoice data