Plans & Billing — Domain Map

This page explains the current consolidated Plans & Billing model. Legacy request, feature, add-on, and override entities are not part of the active commercial domain.

The four layers

1. Catalog (platform-global): Plan, Limit, PlanLimit, effective-dated PlanPrice and LimitPrice, plus country, currency, and discount-code records.
2. Tenant entitlement snapshot: TenantSubscription records status and period dates; TenantSubscriptionEntitlement freezes the Limit values and usage periods granted to that subscription.
3. Commercial orders: OrderSubscription unifies new subscription, custom plan, plan change, and limit increase. OrderSubscriptionItem stores immutable priced-line snapshots.
4. Billing: every order has exactly one Invoice; its InvoiceItem lines, optional DiscountCodeUsage, and optional single PaymentRecord preserve the financial snapshot.

Authority & naming clarifications

• PlanPrice is the authoritative plan-price source for plan, country, currency, billing cycle, and effective date. Plan has no inline price or currency authority.
• Capabilities are Limits. Boolean capabilities use PlanLimit values 0/1; there is no PlanFeature entity.
• BillingPeriod has one member, Monthly. It is the Billing Cycle — when a tenant is charged — and there is nothing to choose.
• SubscriptionTerm is how long the customer subscribed for: 1, 3, 6, or 12 months. Its numeric value is the month count. It is persisted on both the order and the subscription, and it is what selects which discount on the price row applies.
• Duration discounts belong to the price row. PlanPrice carries a percentage for each of the four durations, and LimitPrice carries its own percentage, so a discount can differ by plan, country, currency, and effective period. There is no global discount setting.
• LimitUsagePeriod is the reset window stored on Limit and snapshotted to the subscription entitlement. It is not the billing cycle.
• Order status moves through Draft, Submitted, Approved, then Applied after full payment verification; Rejected and Cancelled are terminal alternatives.
• Payment state belongs to PaymentRecord, not the order. Partial payments are not supported.
• An order that comes to zero has no payment record at all. It is approved and applied directly, its invoice reaches Paid with a zero total, and the interface says "Payment not required" rather than implying a payment was made.
• OrderCompanyProfile holds the company details submitted with one order: organization, country, contact, activation account, phone, notes, and an optional logo. It is a historical snapshot of what was submitted and approved, and it is read only through its owning order.

What appears in the sidebar vs stays internal

• Tenant navigation: Current Subscription (/Tenant/Subscription), Orders (/Tenant/Orders), Create Order (/Tenant/Orders/Create), and Invoices (/Tenant/Invoices).
• Website navigation: an authenticated website user can list owned orders at /CommercialOrders. A standard plan is confirmed at /CommercialOrders/StandardPlan; the public custom builder is /CommercialOrders/CustomPlan.
• Internal records: order/invoice lines, payment records, discount usage, and entitlement snapshots are managed through their owning workflow rather than standalone tenant pages.

Common confusion

• “Custom plan request” and “limit increase request” are user-facing names for OrderSubscription types, not separate request tables.
• The effective plan resolver reads the active subscription's frozen entitlement snapshot. A paid limit-increase order replaces the purchased values in that snapshot; a plan change rebuilds it from the selected plan plus purchased order lines.