Entitlement
You might say
A user bought a Pro subscription; how should the backend check if they can access this export feature?
Determine which features or usage limits an account can access based on its paid subscriptionFor example, Free accounts can generate 3 images per month while Pro accounts export unlimited HD files. Billing systems handle charges, while entitlements translate that paid status into concrete feature gates and quotas. Enforce rules on the server rather than just hiding upgrade banners in the browser.
Know first
EntitlementsFeature Entitlement
Entitlement≠Authorization
Authorization checks permissions by identity and role (such as admin or member); Entitlement checks access rights and quotas granted by commercial contracts and billing plans (such as Free or Pro).
Entitlement≠Authentication
Authentication proves who the caller is; Entitlement determines what that identity is licensed to access.
When to use it
- Verify feature entitlements on the server for each protected API callEvery sensitive action goes through an authorization check.Current user→Authorization rule→Allow / deny
- Sync subscription changes via webhooks to keep entitlement records freshRecord administrative actions16:42 · admin_u7disabled user_u23reason: repeated abuse
- Separate boolean feature gates from metered usage limits and token quotasDeny by default; allow as neededDefaultDENYExplicitly allowviewer → read
- Revoke privileges immediately when a billing cycle ends or a refund occursBeyond roles, check the relationship to the resource.Current useru_23Post authoru_23ResultEdit allowed
When NOT to use it
- Rely only on hiding paid buttons in the client while leaving the API openHiding a button does not secure the endpoint.PageNo delete button → Direct requestDELETE /users/42 → 204
- Hardcode secret admin keys or customer bypass tokens in browser codeAn identity claimed by the frontend can be forged.POST /api/admin/delete{ "userId": "u_23", "role": "admin" }
- Make live HTTP requests to the payment provider on every user actionThe same rule is scattered across several placesusers.tsCheck adminorders.tsForgot to checkreports.tsDifferent rule
- Confuse internal team roles with billing plans: an admin without a plan lacks Pro accessSigning in does not mean you can view all data.Signed in→Access someone else's bill→Should be 403
Anatomy
Planmaps toFeature GateandUsage Quota
The commercial plan purchased via payment provider, such as Free, Pro, or Team
Boolean flag enabling specific features such as HD export or watermark removal
Numeric limit such as 5,000 monthly API calls or 10 active projects
Variants
Feature Gate
hasEntitlement("hd_export")
Control UI displays and API access based on whether a capability is unlocked.
Usage Quota
usedCredits < maxCredits
Meter access by call count, storage volume, or generation tokens.
Seat Limit
currentSeats <= planSeats
Multi-user products restricting team member invites by purchased seats.
Typical use cases
Free versus Pro feature gating
Feature gateHD export gated by plan
Current planFree
→
HD exportRequires Pro entitlement
Server verifies export_hd record before streaming response
Monthly AI token quota deductions
Usage quotaDeducting remaining tokens per call
Monthly quota100 callsUsed99 callsState1 call left
Requests are blocked when depleted with an upgrade prompt
Automatic expiration on subscription lapse
Plan changeWebhook triggers entitlement updates
User pays→Stripe Webhook→Record Pro access
Persists asynchronously to app database for immediate API checks
Seat count limitations for team workspaces
Seat limitRestricting team member count
Purchased seats5 seatsActive members5 membersInvite moreAdd seats required
Prevents unpaid workspaces from inviting unlimited teammates
Further reading