Billing Entities¶
Why This Exists¶
This document defines Billing Domain entities with identity.
Owner¶
The owner is the Chief Product Officer and Enterprise Architect.
Business Value¶
Entity definitions make billing account, subscription, invoice, payment, entitlement, renewal, and cancellation workflows consistent.
Entity Catalogue¶
| Entity | Purpose | Key attributes | Business rules | Relationships | MVP status |
|---|---|---|---|---|---|
| Billing Account | Commercial account for an organization. | BillingAccountId, OrganizationId, currency, billing contact, status. | Must reference OrganizationId. | Has subscriptions and invoices. | MVP |
| Subscription Plan | Defines commercial package. | PlanId, code, name, status, limits, entitlements. | Active plans require limits and entitlements. | Used by subscriptions. | MVP |
| Trial | Defines trial access period. | TrialId, SubscriptionId, start, end, status. | Must have end date and conversion rule. | Belongs to subscription. | MVP |
| Subscription | Tracks accepted plan state. | SubscriptionId, BillingAccountId, plan, cycle, status. | Must have one current status. | Has entitlements, invoices, renewals. | MVP |
| Invoice | Requests payment. | InvoiceId, invoice number, amount, currency, due date, status. | Issued invoices must reconcile line items. | Has line items and payments. | MVP |
| Invoice Line Item | Itemized charge or adjustment. | LineItemId, description, amount, tax, period. | Cannot be changed after issue except adjustment. | Belongs to invoice. | MVP |
| Payment | Tracks payment attempt or settlement. | PaymentId, invoice, amount, provider, status. | Provider callbacks must be deduplicated. | May create failure. | MVP |
| Payment Failure | Tracks failed payment recovery. | FailureId, reason, attempt count, status, next action. | Must reference failed payment. | May request notification. | MVP |
| Entitlement | Grants access to capability or feature. | EntitlementId, subscription, capability, limit, effective dates. | Must derive from subscription state. | Used by platform access. | MVP |
| Usage Record | Tracks measured consumption. | UsageRecordId, unit, quantity, period, source. | Must identify source and period. | Feeds usage limits. | Later |
| Renewal | Tracks subscription renewal lifecycle. | RenewalId, subscription, scheduled date, status. | Must respect billing cycle. | May issue invoice. | MVP |
| Cancellation | Tracks cancellation request and effect. | CancellationId, subscription, reason, effective date, status. | Must preserve billing history. | Ends or modifies subscription. | MVP |
Entity Design Notes¶
Billing entities are commercial evidence. They should preserve historical plan versions, accepted terms, invoices, payments, failures, and entitlement decisions.