The Complete Guide to SaaS Entitlements

What are SaaS Entitlements?

Entitlements answer the question: "What is this user allowed to do?"

In SaaS, this usually means: "What features does their subscription include?"

An entitlement system:

Entitlements vs Feature Flags

These terms are often confused, but they serve different purposes.

Feature Flags

Control feature rollout and availability.

Feature flags are controlled by your engineering team. They're about releasing software safely.

Entitlements

Control access based on billing/subscription status.

Entitlements are controlled by billing status. They're about who has paid for what.

The problem: Many teams use feature flags for entitlements. This creates sync issues—when a customer upgrades, someone (or some code) must flip their flags.

Read more: Entitlements Over Feature Flags

Types of Entitlements

Boolean Features

Simple on/off access.

Usage Limits

Quantity-based access.

Tiered Features

Features with different levels.

Implementing Entitlements

The Basic Pattern

1. Define entitlements per plan

2. When checking access, look up customer's current subscription

3. Get the plan from the subscription

4. Check if the plan includes the entitlement

Without a Platform (DIY)

// You maintain this mapping

const planEntitlements = {

free: {

features: ['basic_analytics'],

limits: { api_calls: 1000 }

},

pro: {

features: ['basic_analytics', 'advanced_analytics', 'exports'],

limits: { api_calls: 100000 }

}

};

// Check access

async function hasFeature(customerId, feature) {

const subscription = await getSubscription(customerId);

const plan = planEntitlements[subscription.planId];

return plan.features.includes(feature);

}

Problems with DIY:

With StackBE

// Define entitlements in StackBE dashboard when creating plans

// Check access - StackBE handles the rest

const { hasAccess } = await stackbe.entitlements.check(

customerId,

'advanced_analytics'

);

if (!hasAccess) {

return showUpgradePrompt();

}

StackBE:

Entitlement Checks in Practice

In Your Backend

Protect API endpoints:

app.post('/api/export', async (req, res) => {

const { hasAccess } = await stackbe.entitlements.check(

req.customerId,

'exports'

);

if (!hasAccess) {

return res.status(403).json({

error: 'Upgrade required',

upgradeUrl: '/pricing'

});

}

// Proceed with export

});

In Your Frontend

Show/hide UI elements:

function Dashboard() {

const { entitlements } = useCustomer();

return (

<div>

<BasicAnalytics />

{entitlements.includes('advanced_analytics') ? (

<AdvancedAnalytics />

) : (

<UpgradePrompt feature="advanced_analytics" />

)}

</div>

);

}

Usage Limit Checks

Track and enforce limits:

// Track usage

await stackbe.usage.track(customerId, 'api_calls');

// Check limit

const { hasAccess, current, limit } = await stackbe.entitlements.checkLimit(

customerId,

'api_calls'

);

if (!hasAccess) {

return res.status(429).json({

error: 'API limit exceeded',

current,

limit,

upgradeUrl: '/pricing'

});

}

Handling Edge Cases

Grace Periods

When payment fails, should access continue?

Best practice: Yes, for a period (7-14 days). Don't punish customers for credit card issues. StackBE supports configurable grace periods.

Subscription Changes Mid-Cycle

Customer upgrades from Pro to Enterprise mid-month.

Best practice: Grant new entitlements immediately. Most platforms handle proration automatically.

Cancellation

Customer cancels but has time remaining on their billing period.

Best practice: Keep access until period ends. They paid for that time. Use `cancelAtPeriodEnd` status.

Downgrade Gotchas

Customer downgrades from Enterprise (5 team members) to Pro (3 team members) but has 5 active members.

Best practice: Allow the downgrade to process but block adding new members. Notify them to reduce to 3 before next billing cycle.

Entitlements Best Practices

1. Gate in the Backend

Always enforce entitlements server-side. Frontend checks are for UX, not security.

2. Cache Thoughtfully

Don't hit your entitlements API on every request. Cache with reasonable TTL (1-5 minutes). Invalidate on subscription webhooks.

3. Fail Gracefully

If entitlements check fails (network error), decide on default behavior. For most features, temporarily allowing access is better than breaking the app.

4. Show Upgrade Paths

When blocking access, show clear upgrade options. "This feature is available on Pro" with a link to upgrade.

5. Log Access Denials

Track when users hit entitlement limits. This is valuable data for pricing and product decisions.

Getting Started

1. List your features - What should be gated by plan?

2. Define plans - What entitlements does each plan include?

3. Implement checks - Backend enforcement, frontend UX

4. Handle edge cases - Grace periods, cancellations, etc.

5. Monitor and iterate - Use access data to inform pricing

StackBE handles entitlements tied to subscriptions out of the box. Define features per plan, check access via API.