Invoices
The InvoiceGenerationService creates, finalizes, and manages invoices for tenant billing periods. Invoices contain line items derived from usage aggregates, support discounts and tax calculations, integrate with Stripe for payment collection, and include late payment tracking with grace periods.
Invoice Lifecycle
| Status | Description |
|---|---|
DRAFT | Invoice created but not yet finalized |
PENDING | Finalized, awaiting payment |
PAID | Payment received in full |
PARTIALLY_PAID | Partial payment received |
OVERDUE | Past due date without full payment |
VOID | Cancelled/voided invoice |
UNCOLLECTIBLE | Marked as uncollectible |
Generate an Invoice
Endpoint: POST /api/v1/billing/tenants/:tenantId/invoices
| Parameter | Type | Description |
|---|---|---|
subscriptionId | UUID | Subscription to invoice |
curl -X POST "http://localhost:8087/api/v1/billing/tenants/550e8400/invoices?subscriptionId=sub-001" \
-H "Authorization: Bearer ${TOKEN}"List Tenant Invoices
Endpoint: GET /api/v1/billing/tenants/:tenantId/invoices
Get Invoice
Endpoint: GET /api/v1/billing/invoices/:invoiceId
Finalize Invoice
Endpoint: POST /api/v1/billing/invoices/:invoiceId/finalize
Transitions the invoice from DRAFT to PENDING and triggers payment collection through Stripe.
Download Invoice PDF
Endpoint: GET /api/v1/billing/invoices/:invoiceId/pdf
Returns the invoice as a downloadable PDF file.
Void Invoice
Endpoint: POST /api/v1/billing/invoices/:invoiceId/void
| Parameter | Type | Description |
|---|---|---|
reason | String | Reason for voiding |
Invoice Entity
| Field | Type | Description |
|---|---|---|
id | UUID | Invoice identifier |
invoiceNumber | String | Unique invoice number |
tenantId | UUID | Owning tenant |
subscription | Subscription | Associated subscription |
status | InvoiceStatus | Current invoice status |
periodStart | LocalDate | Billing period start |
periodEnd | LocalDate | Billing period end |
issueDate | LocalDate | Date invoice was issued |
dueDate | LocalDate | Payment due date |
subtotal | BigDecimal | Sum of line items |
discountAmount | BigDecimal | Total discount applied |
taxAmount | BigDecimal | Calculated tax |
taxRate | BigDecimal | Tax rate percentage |
total | BigDecimal | Final total (subtotal - discount + tax) |
amountPaid | BigDecimal | Amount paid so far |
amountDue | BigDecimal | Remaining balance (total + late fees - paid) |
currency | String | Currency code (default: USD) |
stripeInvoiceId | String | Stripe invoice reference |
lineItems | List | Invoice line items |
Late Payment Handling
The invoice entity includes fields for late payment tracking:
| Field | Type | Description |
|---|---|---|
gracePeriodEndsAt | LocalDate | Default: due date + 15 days |
lateFeeApplied | Boolean | Whether a late fee has been applied |
lateFeeAmount | BigDecimal | Total late fees added |
consecutiveUnpaidMonths | Integer | Months of consecutive non-payment |
firstReminderSentAt | LocalDateTime | First payment reminder timestamp |
secondReminderSentAt | LocalDateTime | Second reminder timestamp |
lateWarningSentAt | LocalDateTime | Late warning notification timestamp |
The LatePaymentService manages escalation: first reminder, second reminder, late warning, late fee application, and eventually marking invoices as uncollectible.