Billing Domain Events¶
Why This Exists¶
This document defines events published by the Billing Domain.
Owner¶
The owner is the Chief Product Officer and Enterprise Architect.
Business Value¶
Billing events allow platform access, Notification, Analytics, and internal operations to respond to subscription lifecycle changes without taking ownership of billing facts.
Event Metadata¶
Every Billing event should include:
- EventId.
- EventType.
- OccurredAt.
- BillingAccountId.
- OrganizationId where applicable.
- SubscriptionId where applicable.
- InvoiceId or PaymentId where applicable.
- CorrelationId.
- CausationId.
- SchemaVersion.
Event Catalogue¶
| Event | Trigger | Payload | Consumers | Business value |
|---|---|---|---|---|
| BillingAccountCreated | Billing account is created. | BillingAccountId, OrganizationId, currency. | Analytics, Notification. | Establishes commercial account. |
| SubscriptionStarted | Subscription begins. | SubscriptionId, plan, status, cycle. | Platform, Analytics, Notification. | Grants access and starts lifecycle. |
| TrialStarted | Trial begins. | TrialId, SubscriptionId, start, end. | Notification, Analytics. | Supports onboarding and conversion. |
| TrialEndingSoon | Trial approaches end date. | TrialId, end date, plan. | Notification. | Prompts conversion action. |
| SubscriptionPlanChanged | Subscription changes plan. | SubscriptionId, previous plan, new plan, effective date. | Platform, Analytics, Notification. | Updates entitlements. |
| EntitlementsUpdated | Entitlements change. | SubscriptionId, entitlement list, effective dates. | Platform, Analytics. | Controls access. |
| UsageLimitReached | Usage reaches or exceeds limit. | SubscriptionId, limit, usage, period. | Notification, Intelligence, Analytics. | Supports upgrade or control. |
| InvoiceIssued | Invoice is issued. | InvoiceId, amount, due date, status. | Notification, Analytics. | Starts payment workflow. |
| InvoicePaid | Invoice is paid. | InvoiceId, payment ID, paid at. | Analytics, Notification. | Confirms settlement. |
| PaymentSucceeded | Payment succeeds. | PaymentId, amount, provider reference. | Analytics, Notification. | Confirms payment. |
| PaymentFailed | Payment fails. | PaymentId, reason, next action. | Notification, Analytics. | Starts recovery. |
| SubscriptionRenewed | Subscription renews. | SubscriptionId, renewal date, next renewal date. | Analytics, Notification. | Continues access. |
| SubscriptionPastDue | Payment or invoice issue moves subscription past due. | SubscriptionId, reason, effective date. | Platform, Notification, Analytics. | Protects revenue and access. |
| SubscriptionSuspended | Subscription access is suspended. | SubscriptionId, reason, effective date. | Platform, Notification, Analytics. | Enforces commercial state. |
| SubscriptionCancelled | Subscription is cancelled. | SubscriptionId, reason, effective date. | Platform, Notification, Analytics. | Ends renewal or access. |
| BillingNotificationRequested | Billing requests notification delivery. | Notification type, source reference, priority. | Notification. | Communicates billing facts. |
Event Flow¶
sequenceDiagram
participant Billing
participant Provider as Payment Provider
participant Platform
participant Notification
participant Analytics
Billing->>Provider: Attempt payment
Provider-->>Billing: Payment failed callback
Billing->>Billing: Record payment failure
Billing-->>Notification: BillingNotificationRequested
Billing-->>Analytics: PaymentFailed
Billing-->>Platform: SubscriptionPastDue if policy applies
Cross-Domain Rule¶
Billing events may affect platform access through entitlement updates. Operational domains must consume entitlement decisions rather than creating their own subscription state.