Billing Aggregates¶

Why This Exists¶

This document defines aggregate boundaries for the Billing Domain.

Owner¶

The owner is the Chief Product Officer and Enterprise Architect.

Business Value¶

Aggregate boundaries keep commercial state consistent across subscriptions, invoices, payments, entitlements, renewals, cancellations, and payment failures.

Aggregate Map¶

flowchart TD
    Account[Billing Account Aggregate]
    Plan[Plan Catalogue Aggregate]
    Subscription[Subscription Aggregate]
    Entitlement[Entitlement Aggregate]
    Invoice[Invoice Aggregate]
    Payment[Payment Aggregate]
    Failure[Payment Failure Aggregate]
    Renewal[Renewal Aggregate]
    Cancellation[Cancellation Aggregate]

    Account --> Subscription
    Plan --> Subscription
    Subscription --> Entitlement
    Subscription --> Invoice
    Invoice --> Payment
    Payment --> Failure
    Subscription --> Renewal
    Subscription --> Cancellation

Billing Account Aggregate¶

The Billing Account aggregate owns billing contacts, organization reference, billing address reference or billing address details, tax metadata, currency preference, and payment method references.

Invariants¶

A billing account must reference one OrganizationId.
A billing account must have at least one billing contact or billing contact rule.
Billing account changes must be auditable.

Plan Catalogue Aggregate¶

The Plan Catalogue aggregate owns the plan definitions, plan status, plan limits, and entitlement packages for Free, Starter, Professional, Business, and Enterprise.

Invariants¶

A plan must have a unique plan code.
Active plans must define included entitlements and limits.
Enterprise plans may reference negotiated terms without changing standard plan history.

Subscription Aggregate¶

The Subscription aggregate owns accepted subscription state, plan, billing cycle, trial status, renewal status, cancellation status, and current access state.

Invariants¶

A subscription must belong to one billing account.
A subscription must reference one active or grandfathered plan.
Subscription status must be derived from accepted events, not external assumptions.
Subscription changes must produce domain events.

Entitlement Aggregate¶

The Entitlement aggregate owns capability access and usage limits granted by subscription state.

Invariants¶

Entitlements must be derived from plan, subscription, and overrides.
Entitlements must have effective dates.
Usage limits must identify the measured unit and reset period.

Invoice Aggregate¶

The Invoice aggregate owns invoice number, line items, amount due, tax, currency, due date, status, and payment allocation references.

Invariants¶

An issued invoice must have immutable line items except credit or adjustment records.
Invoice totals must reconcile to line items.
Paid invoices must reference successful payment allocation.

Payment Aggregate¶

The Payment aggregate owns payment attempts, provider references, settlement status, amount, currency, and failure details where applicable.

Invariants¶

A payment must reference a billing account or invoice.
Payment provider callbacks must be deduplicated.
Failed payments must create failure records or update failure workflow.

Renewal And Cancellation Aggregates¶

Renewal owns scheduled continuation of a subscription. Cancellation owns cancellation request, effective date, reason, retention context, and final access impact.

Invariants¶

Renewal must respect subscription status and billing cycle.
Cancellation must define whether it is immediate or end-of-period.
Cancellation cannot delete historical invoice or payment records.