Billing Module Specification¶

Purpose¶

The billing module implements the Billing Domain inside the Spring Boot Modulith. It owns commercial account state, subscription plans, trials, subscriptions, entitlements, usage limits, invoices, payments, payment failures, renewals, cancellations, billing notifications as requests, and payment provider callback interpretation.

Owned Domain¶

Billing owns subscription, entitlement, invoice, and payment state. It does not own customer organization profile facts, product capability source definitions, notification delivery, analytics metrics, AI reasoning, or operational domain facts.

Owned Aggregates¶

Aggregate	Responsibility
Billing Account	Billing contacts, OrganizationId reference, tax context, currency preference, and payment method references.
Plan Catalogue	Plan definitions, plan status, plan limits, and entitlement packages.
Subscription	Accepted subscription state, plan, billing cycle, trial, renewal, cancellation, and access state.
Entitlement	Capability access and usage limits derived from subscription and plan state.
Invoice	Invoice number, line items, amount, tax, currency, due date, status, and payment allocation.
Payment	Payment attempts, provider references, settlement status, amount, currency, and failures.
Payment Failure	Failed payment recovery, reason, retry count, status, and next action.
Renewal	Scheduled subscription continuation and renewal outcome.
Cancellation	Cancellation request, effective date, reason, retention context, and access impact.

Owned Entities¶

Billing Account, Subscription Plan, Trial, Subscription, Invoice, Invoice Line Item, Payment, Payment Failure, Entitlement, Usage Record, Renewal, and Cancellation.

Owned Value Objects¶

BillingAccountId, SubscriptionId, PlanCode, SubscriptionStatus, BillingCycle, TrialPeriod, Money, InvoiceNumber, InvoiceStatus, PaymentStatus, PaymentFailureReason, EntitlementCode, UsageUnit, UsageLimit, RenewalDate, CancellationReason, ProviderReference, and TaxAmount.

Commands¶

Command	Responsibility
CreateBillingAccount	Create commercial account for an organization.
CreatePlan	Create or revise plan catalogue entry.
StartTrial	Start trial access where eligible.
StartSubscription	Start accepted subscription state.
ChangeSubscriptionPlan	Change subscription plan and effective date.
EvaluateEntitlements	Recalculate entitlements and limits.
RecordUsage	Record measured usage for limit evaluation.
IssueInvoice	Issue invoice with immutable line items.
ProcessPayment	Start or record payment attempt.
ProcessPaymentCallback	Validate, deduplicate, and interpret provider callback.
RecordPaymentFailure	Create failure workflow and recovery action.
RenewSubscription	Record renewal outcome.
CancelSubscription	Record cancellation request and effective access impact.
RequestBillingNotification	Request Notification delivery for billing fact.

Queries¶

Query	Responsibility
GetBillingAccount	Return billing account summary.
GetPlans	Return plan catalogue, limits, and entitlements.
GetSubscription	Return subscription state, cycle, plan, and renewal context.
GetEntitlements	Return effective entitlements for access decisions.
GetUsage	Return usage records and limit state.
GetInvoices	Return invoices and invoice status.
GetPayments	Return payment attempts and settlement state.
GetPaymentFailures	Return failure workflow state.
GetRenewal	Return renewal schedule and outcome.
GetCancellation	Return cancellation state and effective date.

Application Services¶

BillingAccountApplicationService, PlanCatalogueApplicationService, TrialApplicationService, SubscriptionApplicationService, EntitlementApplicationService, UsageApplicationService, InvoiceApplicationService, PaymentApplicationService, PaymentCallbackApplicationService, PaymentFailureApplicationService, RenewalApplicationService, CancellationApplicationService, and BillingNotificationApplicationService.

Domain Services¶

TrialEligibilityService, PlanSelectionService, EntitlementEvaluationService, UsageLimitService, InvoiceGenerationService, PaymentProcessingService, PaymentFailureRecoveryService, RenewalService, CancellationService, BillingNotificationService, and EnterpriseTermsService.

Policies¶

Trial Eligibility Policy, Plan Selection Policy, Entitlement Evaluation Policy, Usage Limit Policy, Invoice Generation Policy, Payment Processing Policy, Payment Failure Recovery Policy, Renewal Policy, Cancellation Policy, Billing Notification Policy, and Enterprise Terms Policy.

Repositories¶

BillingAccountRepository, BillingContactRepository, PlanRepository, PlanLimitRepository, PlanEntitlementRepository, SubscriptionRepository, TrialRepository, EntitlementRepository, UsageRecordRepository, InvoiceRepository, InvoiceLineItemRepository, PaymentRepository, PaymentFailureRepository, RenewalRepository, CancellationRepository, ProviderCallbackRepository, and BillingAuditRepository.

Events Published¶

BillingAccountCreated, SubscriptionStarted, TrialStarted, TrialEndingSoon, SubscriptionPlanChanged, EntitlementsUpdated, UsageLimitReached, InvoiceIssued, InvoicePaid, PaymentSucceeded, PaymentFailed, SubscriptionRenewed, SubscriptionPastDue, SubscriptionSuspended, SubscriptionCancelled, and BillingNotificationRequested.

Events Consumed¶

OrganizationRegistered, OrganizationActivated, OrganizationSuspended, OrganizationArchived, PaymentProviderCallbackReceived, AdminActionRecorded, PolicyConfigurationChanged, AIRecommendationProduced, UsageMeasured, and FeatureFlagUpdated.

REST API Responsibility¶

The module owns API responsibilities for billing accounts, plans, subscriptions, trials, entitlements, usage, invoices, payments, payment provider callbacks, payment failures, renewals, and cancellations. Final endpoint schemas are deferred.

Database Ownership¶

Billing owns conceptual persistence for billing accounts, contacts, plans, plan limits, plan entitlements, subscriptions, trials, entitlements, usage records, invoices, invoice line items, payments, payment failures, renewals, cancellations, provider callbacks, and billing audit logs.

Module Dependencies¶

Allowed dependencies are shared kernel identifiers, identity authorization context, organization references, payment provider integration adapters, notification billing notification requests, analytics billing events, administration approved policy configuration, and intelligence plan explanation support.

Forbidden Dependencies¶

Billing must not mutate Organization profile, Notification delivery state, Analytics projections, Intelligence reasoning records, or operational domain facts. Other modules must not create their own subscription or entitlement state.

AIOS Interaction Boundary¶

AIOS may explain plans, identify upgrade signals, or suggest retention and upgrade messaging. Billing owns accepted commercial state, entitlement decisions, invoices, payments, and notification request facts.

Security And Tenant Rules¶

Billing data is tenant-scoped commercial data and requires least-privilege access.
Payment provider callbacks must be validated, deduplicated, and auditable.
Sensitive payment instrument data must not be stored unless explicitly governed.
Entitlement checks must be effective-dated and fail closed where required.
Invoice, payment, and cancellation changes require audit context.

Test Strategy¶

Tests must cover plan selection, trial eligibility, subscription lifecycle, entitlement recalculation, usage limits, invoice totals, payment callback deduplication, payment failure recovery, renewal, cancellation, notification requests, event publication, idempotent event consumption, tenant filtering, and Spring Modulith boundaries.

Future Microservice Extraction Notes¶

Billing can be extracted as commercial workflows mature. Extraction requires stable entitlement APIs, payment callback contracts, notification event contracts, audit retention, tenant-aware migration, and no direct subscription table access from platform modules.

Mermaid Component Diagram¶

flowchart TD
    Api[billing.api.rest]
    App[billing.application.service]
    Command[billing.application.command]
    Query[billing.application.query]
    Domain[billing.domain.model]
    Policy[billing.domain.policy]
    Repo[billing.infrastructure.persistence]
    Integration[billing.infrastructure.integration]
    Messaging[billing.infrastructure.messaging]
    Organization[organization reference]
    Provider[payment provider]
    Notification[notification requests]
    Analytics[analytics projections]
    Admin[administration policy config]

    Api --> App
    App --> Command
    App --> Query
    App --> Domain
    Domain --> Policy
    App --> Repo
    App --> Integration
    Integration --> Provider
    App --> Messaging
    App --> Organization
    Messaging --> Notification
    Messaging --> Analytics
    App --> Admin