SaaS Tiers & Entitlements Vocabulary — Multi-Tenant SaaS Architecture Exercises

1 / 5

A SaaS product has three tiers: Basic, Pro, and Enterprise. During a code review, an engineer comments: "Feature X is gated behind the Pro tier." What does feature gating mean technically in a SaaS context?

Feature gating is the mechanism that makes SaaS tiering commercially enforceable — it connects a tenant's paid plan to the features they can actually access.

How feature gating works at runtime:
① An incoming request arrives (user clicks "Export to CSV")
② The application calls the entitlement service: "Is tenant-abc entitled to feature:csv-export?"
③ The entitlement service looks up the tenant's plan tier in the tenant configuration store
④ If the tenant is Pro or above: returns { permitted: true }
⑤ If the tenant is Basic: returns { permitted: false, reason: 'pro_required', upgradeUrl: '/billing/upgrade' }
⑥ The application either renders the feature or shows an upgrade prompt

Implementation patterns:

Layer	Gating approach	Trade-off
Frontend (UI)	Hide or disable the UI element	UX benefit, but must also gate at the API — UI gating alone is not security
API layer	Return 403 or upgrade prompt if not entitled	Security boundary — this is the authoritative enforcement point
Business logic	Check entitlement before executing the operation	Granular, but can scatter checks across the codebase without a centralised service

Best practice: always enforce gating at the API/service layer — never trust UI-only gating. A determined user can bypass UI restrictions with direct API calls.

Key vocabulary:
• Feature gating — conditional access to a product feature based on a tenant's commercial plan entitlement
• Entitlement check — the runtime evaluation of whether a tenant/user is permitted to use a specific feature
• Upgrade prompt — the UI pattern shown to tenants on insufficient plans, directing them to upgrade
• HTTP 403 Forbidden — the correct status code for refusing a request due to insufficient entitlement (not 401, which implies authentication failure)

2 / 5

A staff engineer proposes extracting feature-gating logic into a dedicated entitlement service. A junior engineer asks: "Why not just check the plan tier inline in each microservice?" What is an entitlement service and why does it justify being a separate service?

An entitlement service encapsulates all the rules about "who can use what" in a single, authoritative place — preventing the logic from spreading across dozens of microservices.

What an entitlement service must evaluate:

Input	Example	Managed by
Plan tier	Tenant is on Pro plan — feature:csv-export permitted	Billing system → tenant config store
Add-on purchase	Tenant purchased "Advanced Analytics" add-on	Billing system
Trial override	Tenant has 60-day trial of Enterprise AI features (expires 2026-06-01)	Sales team via admin portal
Custom override	Legacy customer grandfathered into features removed from their plan	CS team via admin portal
Contractual limit	Enterprise customer negotiated 50 team seats (not plan default)	Sales contract → entitlement store

What goes wrong without a centralised entitlement service:
• The API service checks plan === 'pro' directly — but doesn't know about add-ons
• The mobile app checks a different flag — and grandfathered users see inconsistent access
• A trial expires and access is revoked in some services but not others
• Adding a new pricing tier requires changes across every microservice that contains inline plan checks

Entitlement service API design:

POST /entitlements/check
{ tenantId: "abc", feature: "csv-export" }
→ { permitted: true, reason: "pro_plan", expiresAt: null }

Key vocabulary:
• Entitlement service — the centralised authority for evaluating feature access based on plan, add-ons, overrides, and trial grants
• Entitlement override — a manual grant or restriction that supersedes the default plan-based entitlement
• Add-on — a purchasable feature module that extends the base plan's entitlements
• Grandfathered entitlement — an access right retained by legacy customers when a feature is removed from or restructured in their plan

3 / 5

The product team is designing quota enforcement for a new SaaS feature. A debate arises: should the system use a hard limit or a soft limit? Which answer correctly distinguishes between the two?

The choice between hard and soft limits has a direct impact on both user experience and revenue — soft limits are a deliberate conversion mechanism, not a technical shortcut.

Property	Hard Limit	Soft Limit
Behaviour at threshold	Request rejected — operation blocked	Request permitted — warning + upsell shown
HTTP response	403 Forbidden or 413 Content Too Large	200 OK with advisory message in response body or email
Best use case	Resource-constrained limits: storage full, seat count reached	Conversion-oriented limits: API call overages, seat warnings
Business rationale	Prevent platform cost overruns; enforce fair use	Drive upsell without disrupting user workflow
User experience	Disruptive — must upgrade before continuing	Non-disruptive — user continues working; upgrade is optional (for now)

Common SaaS patterns combining both:
• Storage: soft limit at 80% (banner + upsell email), hard limit at 100% (uploads blocked)
• API calls: soft limit at plan quota (notification + upgrade prompt), hard limit at 2× plan quota (service protection)
• Seats: soft limit at plan maximum (can add more but see upgrade prompt), hard limit only for contractual enterprise customers

Key vocabulary:
• Hard limit — a quota enforced by rejecting the operation; the system will not allow usage beyond this threshold
• Soft limit — a threshold that triggers a warning and upsell prompt without blocking the operation
• Quota overage — usage that exceeds the plan limit; handled differently depending on hard vs soft enforcement
• Upsell prompt — an in-app or email message surfaced when a tenant approaches a limit, directing them to a higher plan

4 / 5

An engineering lead proposes replacing hardcoded feature flags in the application code (if (tenant.plan === 'pro') { ... }) with a configuration-driven entitlement system. A sceptical engineer asks: "Why does this justify the extra infrastructure complexity?" What is the strongest argument in favour of the configuration-driven approach?

The commercial cost of hardcoded feature flags compounds as the product matures — what starts as a simple if-statement becomes a deployment dependency for the entire sales motion.

The real cost of hardcoded flags as a SaaS company scales:

Scenario	Hardcoded approach	Config-driven approach
New pricing tier for a campaign	Engineering ticket → code change → PR → deploy	CS/sales creates a new plan config in the admin portal in minutes
30-day enterprise trial on AI feature	Engineering adds a hardcoded tenant ID and expiry — must be removed later	Time-limited override stored in entitlement store with expiry timestamp
Grandfathering a legacy customer	Another hardcoded tenant ID check in the codebase	Custom entitlement override in the config store for that tenant only
A/B testing a new plan structure	Two code paths, feature flags, gradual rollout requires complex branching	Percentage rollout config in the entitlement system

What a configuration-driven entitlement system enables:
• Sales velocity: custom deals closed without waiting for an engineering sprint
• Clean codebase: no accumulation of tenant ID checks and expiry date constants
• Auditability: every entitlement change is logged in the config store with who made it and when
• Rollback safety: a misconfigured entitlement can be reverted without a code deployment

Key vocabulary:
• Configuration-driven entitlement — plan and feature access rules stored in a data store, evaluated at runtime, changeable without code deployment
• Commercial velocity — the speed at which the sales/CS team can create and activate custom commercial arrangements
• Entitlement drift — the accumulation of tenant-specific checks scattered across the codebase over time
• Tenant ID hardcoding — the anti-pattern of embedding specific tenant identifiers directly in application code

5 / 5

A customer success manager says: "Tenant XYZ wants a 60-day trial of the AI features before committing to the Enterprise plan. Can we make that happen?" The engineering lead says yes. What is the correct technical pattern for implementing this?

Time-limited entitlement overrides are a core feature of a mature entitlement service — they enable the sales motion of "try before you buy" without manual operations or code changes.

How the pattern works end-to-end:
① CS manager creates a trial override in the admin portal: feature ai-features, tenant xyz, expires in 60 days
② The entitlement service stores the override with an ISO 8601 expiry timestamp
③ Every time Tenant XYZ accesses an AI feature, the entitlement service checks:
  a. Does an active override exist for xyz + ai-features?
  b. Is expiresAt in the future?
  c. If yes → { permitted: true, expiresAt: "2026-06-10T00:00:00Z" }
④ On day 61 the entitlement service finds the override expired → evaluates the base plan → returns { permitted: false, reason: "enterprise_required" }
⑤ The AI feature surfaces an upgrade prompt automatically — no engineering involvement

Comparison of approaches:

Approach	Scalability	Reliability	Engineering effort
Manual billing tier assignment	Poor — ops overhead per trial	Human error risk	Low initially, high at scale
Hardcoded tenant ID + expiry	Not scalable	Requires code change + deploy to remove	High — every trial needs an engineer
Time-limited entitlement override	Excellent — self-service	Automatic expiry, no manual cleanup	One-time service investment, zero ongoing

Key vocabulary:
• Time-limited entitlement override — an entitlement record with an expiry timestamp that automatically reverts when it passes
• Trial grant — a temporary entitlement to features above a tenant's purchased plan, used for sales trials or beta access
• Automatic reversion — the entitlement service restores plan-based rules when a trial override expires, without manual intervention
• Expiry timestamp — an ISO 8601 datetime stored with the override, checked on every entitlement evaluation