Billing Policies

Why This Exists

This document defines policies that govern Billing Domain behavior.

Owner

The owner is the Chief Product Officer and Enterprise Architect.

Business Value

Policies make subscription, invoice, payment, entitlement, renewal, and cancellation decisions consistent and auditable.

Policy Catalogue

Policy	When it runs	Decision made	Outputs
Trial Eligibility Policy	When an organization requests or starts a trial.	Whether trial is allowed and when it ends.	TrialStarted or rejection.
Plan Selection Policy	When a subscription is created or changed.	Whether the selected plan is valid.	SubscriptionStarted or SubscriptionPlanChanged.
Entitlement Evaluation Policy	When subscription or plan state changes.	Which entitlements and limits apply.	EntitlementsUpdated.
Usage Limit Policy	When usage is recorded or evaluated.	Whether usage is within plan limits.	UsageLimitReached or usage accepted.
Invoice Generation Policy	On billing cycle, plan change, or manual invoice command.	Whether invoice should be issued and which line items apply.	InvoiceIssued.
Payment Processing Policy	When a payment attempt or provider callback occurs.	Whether payment succeeded, failed, or requires review.	PaymentSucceeded or PaymentFailed.
Payment Failure Recovery Policy	After failed payment.	Retry, notify, grace period, past due, suspension, or write-off path.	BillingNotificationRequested, SubscriptionPastDue, SubscriptionSuspended.
Renewal Policy	Before subscription renewal.	Whether subscription renews and under which terms.	SubscriptionRenewed or renewal blocked.
Cancellation Policy	When cancellation is requested.	Whether cancellation is immediate, end-of-period, or rejected.	SubscriptionCancelled.
Billing Notification Policy	When billing events need communication.	Which notification type, priority, and recipient rule should be requested.	BillingNotificationRequested.
Enterprise Terms Policy	When Enterprise subscription uses custom terms.	Whether custom terms are approved and versioned.	SubscriptionStarted or PlanChanged with custom terms.

Payment Failure Recovery

Payment failure handling should be clear and measured:

• Record the failed payment.
• Classify the reason where available.
• Request a billing notification.
• Apply retry policy if appropriate.
• Move subscription to past due when policy threshold is reached.
• Suspend access only when Billing policy permits.

Entitlement Evaluation

Entitlements must be recalculated when:

• A subscription starts.
• A plan changes.
• A trial starts or ends.
• Payment status changes subscription access.
• Enterprise terms are changed.
• Usage limit override is approved.

Policy Flow

flowchart LR
    Subscription[Subscription change]
    Entitlement[Entitlement policy]
    Invoice[Invoice policy]
    Payment[Payment policy]
    Failure[Failure recovery policy]
    Notification[Billing notification policy]

    Subscription --> Entitlement
    Subscription --> Invoice
    Invoice --> Payment
    Payment --> Failure
    Failure --> Notification