Tenant Subscription Management
Short summary (how it works)
Tenant Subscription Management automatically keeps your subscription billing in sync with how many users are actually
active on each Tenant.
Active Tenant Users are rolled up daily and compared to the subscription on the Sales Order. If more users are active
than paid for, the difference is invoiced and the subscription is increased. At renewal, the subscription is adjusted to
match the current number of active users.
Overview
This setup is designed for user-based subscriptions (seat licensing) where customers can add or remove users over time,
and billing should reflect real usage without constantly adjusting subscriptions up and down during a billing period.
The model separates:
- Actual usage (who is active right now)
- Subscription baseline (what is currently paid for and will renew)
This makes billing predictable while still ensuring that additional usage is billed correctly.
Modules involved
In addition to standard vtiger modules, the setup uses:
- Tenants
Represents each customer environment / SaaS tenant.
- Tenant Users (TU)
Each record represents one licensed user belonging to a Tenant.
Typical fields:
- Tenant (relation)
- Product / License type (relation)
- Status (Active / Inactive)
- Start date (and optional End date)
- Sales Orders (SO)
Represents the active subscription.
Each product line represents a license type, and the quantity represents the number of paid seats for the current
period and future renewals.
How the billing logic works
Daily seat rollup (scheduled workflow)
A scheduled workflow runs once per day and performs the following steps:
1. Roll up active Tenant Users
For each Tenant and license type, the system counts how many Tenant Users are currently active.
2. Compare usage with subscription baseline
The active user count is compared with the quantities on the related Sales Order.
3. Handle over-usage (scale up)
If the number of active users is higher than the number of paid seats:
- The difference is invoiced as an adjustment (typically prorated until the next renewal date).
- The Sales Order line quantity is increased so the new seat count becomes the new subscription baseline.
4. Handle under-usage (scale down)
If the number of active users is lower than the number of paid seats:
- No refund is created during the active period.
- Freed seats remain available and can be reused by new users.
This ensures that:
- Additional usage is always billed.
- Temporary reductions in users do not constantly change the subscription mid-period.
Subscription renewal (period start workflow)
At the start of a new billing period (before the recurring invoice is generated):
1. Recalculate the baseline
- The Sales Order quantities are updated to match the current number of active Tenant Users.
- Quantities can go both up or down at renewal.
2. Recurring invoicing
- The normal recurring invoice process uses the updated Sales Order quantities as the basis for the new period’s
subscription invoice.
This ensures that each new period starts with a subscription that reflects the real current usage.
Key principles
- Tenant Users = actual usage
This is the source of truth for how many licenses are really in use.
- Sales Orders = billing baseline
This is what customers are currently paying for and what will renew next period.
- Scale up during the period, right-size at renewal
- During a period: only increases are billed.
- At renewal: the subscription is aligned to real usage (up or down).
Customization
The setup can be adapted to different business rules, for example:
- Different TU statuses (e.g. Pending, Suspended).
- Different proration models for mid-period upgrades.
- Custom pricing or discounts per Tenant or license type.
As long as Tenant Users represent real usage and Sales Orders represent the paid baseline, the model remains simple,
predictable, and flexible.
