Billing Value Objects¶
Why This Exists¶
This document defines immutable or value-based concepts used by the Billing Domain.
Owner¶
The owner is the Chief Product Officer and Enterprise Architect.
Business Value¶
Value objects keep billing calculations, subscription status, plan limits, entitlements, money, dates, and provider references consistent.
Value Object Catalogue¶
| Value object | Purpose | Validation rules |
|---|---|---|
| BillingAccountId | Identifies a billing account. | Must be unique. |
| SubscriptionId | Identifies a subscription. | Must be unique. |
| PlanCode | Identifies plan. | Allowed values: free, starter, professional, business, enterprise. |
| SubscriptionStatus | Tracks subscription state. | Allowed values: trialing, active, past_due, suspended, cancelled, expired. |
| BillingCycle | Defines billing cadence. | Examples: monthly, annual, custom. |
| TrialPeriod | Defines trial start and end. | End date must be after start date. |
| Money | Represents monetary amount. | Must include amount and currency. |
| InvoiceNumber | Human-readable invoice identifier. | Must be unique in billing scope. |
| InvoiceStatus | Tracks invoice lifecycle. | Allowed values: draft, issued, paid, overdue, void, credited. |
| PaymentStatus | Tracks payment state. | Allowed values: pending, processing, succeeded, failed, refunded, disputed. |
| PaymentFailureReason | Classifies failure. | Must use approved failure reason catalogue where possible. |
| EntitlementCode | Identifies granted access. | Must map to approved capability or plan package. |
| UsageUnit | Defines measured usage. | Examples: user, tender, bid, workflow, storage_mb, api_call. |
| UsageLimit | Defines quantity and period. | Must include unit, quantity, and reset period. |
| RenewalDate | Defines next renewal date. | Must align to billing cycle unless custom terms apply. |
| CancellationReason | Captures cancellation reason. | Must use approved reason or structured other text. |
| ProviderReference | Stores payment provider reference. | Must include provider name and external ID. |
| TaxAmount | Stores tax value. | Must include amount, currency, tax rate or tax code. |
Validation Principles¶
- Money values must never be stored without currency.
- Historical invoices must retain plan and pricing context used at issue time.
- Entitlements must have effective date ranges.
- Provider references are not source business facts; Billing owns accepted payment state after validation.