Entitlements model for customer tiers: plans, limits, flags

Why teams need an entitlements model

If you sell more than one tier, you’ll eventually get the same support ticket: “Customer X paid for Pro, but they can’t access Feature Y.” Without a clear system, support can’t fix it directly. A simple access change turns into an engineering task.

The bigger problem is inconsistency. Access rules end up scattered across the product: a checkbox in an admin screen, a hardcoded check in the API, a note in a spreadsheet, and a one-off database update from last quarter. Customers see different behavior in different places, and no one is sure which rule is the real one.

An entitlements model gives you a single source of truth for who can do what, based on their plan and any approved exceptions. It keeps tiers predictable (so pricing stays credible), while still leaving room for real life: a temporary upgrade, a quota bump, or a pilot feature for one account.

“Adjust without engineering” should be concrete. In practice:

• Support changes access in an admin tool by editing data, not by requesting a deploy.
• The product reads the same entitlement data everywhere (backend, web app, mobile).
• Exceptions can be time-bound and reversible, not permanent hacks.
• Changes are logged with who did it, when, and why.

For example, a customer on the Business tier hits a limit on active users during a busy season. Support should be able to grant +10 seats for 14 days, and the system should roll it back automatically when the period ends. Engineering should only get involved when you’re adding a brand-new capability, not when you’re doing routine access adjustments.

The basic pieces: customers, plans, and entitlements

A good entitlements model starts with a few clear objects and clear ownership. If these basics are fuzzy, support ends up asking engineering for “just one more exception” every week.

Here’s a simple set of building blocks:

• Customer (account/tenant): the company or person using your product.
• Subscription: the commercial relationship (trial, active, canceled), often tied to a billing system.
• Plan: the named tier (Free, Pro, Enterprise) that defines the default access.
• Entitlement: the actual allowed behavior, derived from the plan plus any overrides.

Entitlement evaluation is not billing. Billing answers “what should we charge and when?” Entitlements answer “what can this customer do right now?” A customer might be unpaid but still in a grace period, or fully paid but temporarily blocked for compliance. Keep these decisions separate so finance can fix invoices without accidentally changing product access.

Several groups rely on this setup:

• Product defines what plans mean.
• Support needs safe controls to grant or remove access.
• Sales ops needs consistent rules for deals and renewals.
• Finance needs a reliable mapping between what was sold and what access was provided.

Set boundaries early. Make plan contents and customer overrides configurable (so support can act), but keep core behavior in code. Examples of “core behavior” include how you calculate remaining quota, how you handle expired trials, and which actions must be audited.

Flags, limits, and quotas: pick the right type

Most tiering problems get easier when you name the entitlement correctly. There are three common types, and each answers a different question:

• Boolean flags: is something on or off? Example: export_enabled = true.
• Numeric limits: how much is allowed at once? Example: max_seats = 10.
• Quotas: how much can be used over time? Example: api_calls_per_month = 100000.

Flags are best for features that shouldn’t partially work. If export is off, hide the button and block the endpoint too. Limits are best for “capacity” settings that don’t reset, like seats, projects, or saved views.

Quotas need extra care because time matters. Support tickets drop fast when the reset rule is written down and visible in the admin UI.

Scope is the other decision that prevents confusion. A flag like “SAML SSO enabled” is usually account-level. “Max projects” might be workspace-level. “Can run reports” might be user-level if you sell role-based add-ons.

For quotas, pick one reset rule per quota and stick to it:

• Never (lifetime credits)
• Monthly (calendar month)
• Rolling window (last 30 days)
• Per billing period (matches the invoice cycle)

If the reset rule changes by plan, treat the rule itself as part of the entitlement, not tribal knowledge.

A practical database schema for entitlements

A support-friendly entitlements model usually works best when it stays boring: a few tables, clear keys, and time-bounded records you can audit. The goal is to let admins change access by editing data, not shipping code.

Start with four core tables: plans, plan_entitlements, customers, and customer_overrides.

• Plans describe tiers (Free, Pro, Enterprise).
• Plan entitlements describe what each plan includes.
• Customers point to a plan.
• Overrides cover exceptions for a single customer without changing the plan for everyone.

A compact relational shape that works well:

• plans: id, name, description, is_active
• plan_entitlements: id, plan_id, key, type, value, unit, reset_policy, effective_from, effective_to, created_by
• customers: id, name, plan_id, status, created_at
• customer_overrides: id, customer_id, key, type, value, unit, reset_policy, effective_from, effective_to, created_by

The entitlement fields should be consistent across tables. Use a stable key like seats, api_calls, or sso_enabled. Use type to keep evaluation simple (for example: flag, limit, quota). Store unit explicitly (like users, requests, GB). For quotas, keep reset_policy unambiguous (like monthly, daily, never).

Overrides should behave like an allowlist with dates. If a customer has an active override for sso_enabled=true, it should win over the plan value, but only within effective_from and effective_to. This is what makes “grant 10 extra seats for 14 days” a one-row change that expires automatically.

How entitlement evaluation should work

Entitlement evaluation is the small piece of code (or service) that answers one question: “Is this customer allowed to do this right now?” If this part is predictable, everything else stays easier to operate.

Use a clear precedence order and don’t deviate: customer override > plan value > system default. That lets support grant temporary exceptions without changing the plan, and it gives engineering safe defaults when nothing is configured.

A practical evaluation flow:

• Identify the customer/account from the authenticated session (not from the request body).
• Load the customer’s active plan and any active overrides.
• For a given key, return the override if present; otherwise return the plan value; otherwise return the system default.
• If the key is missing everywhere, fail closed for access checks (treat as “not allowed”) and use a sensible default for display-only UI.
• If the key is unknown (not in your registry), treat it as a configuration error, fail closed, and log it for follow-up.

Caching matters because entitlements get checked constantly. Cache the resolved entitlements per customer with a short TTL and an explicit version number. Invalidate when any of these change: plan assignment, plan definition, customer overrides, or customer status (trial, grace, blocked). A simple pattern is “cache by customer_id + entitlements_version,” where support edits bump the version so changes show up quickly.

Multi-tenant safety is non-negotiable. Every query must filter by the current customer/account id, and every cache entry must be keyed by that id. Don’t look up entitlements by email, domain, or plan name alone.

Step by step: a support-friendly workflow to adjust access

A support-friendly workflow keeps the model flexible without turning every edge case into an engineering task. The goal is to make changes safely, leave a trail, and confirm the customer experience.

A safe support flow

Start by finding the right customer record and confirming what they’re asking for, and why. “Need two more seats for a week” is different from “we signed an amendment for a higher tier.” A good admin UI makes it easy to see, in one place, the current plan, customer status, and any active overrides.

Before changing anything, check actual usage against the current limit or quota. Many requests disappear once you see the account isn’t at the cap, or the issue is somewhere else (for example, usage tracking not updating).

When you do need to adjust access, prefer an explicit override instead of editing the plan. Keep overrides narrow (one flag or one limit), include an owner and a reason, and default to an expiry date. Temporary exceptions are common, and they’re easy to forget.

A simple checklist inside your admin tool is usually enough:

• Confirm customer identity, current plan, and request reason.
• Review current usage vs the relevant cap.
• Apply a scoped override and set an expiry.
• Add notes plus a ticket or case reference.
• Verify the result in the product UI using impersonation or a test account.

Always verify the change the way the customer will experience it. If you support impersonation, make it obvious when it’s enabled and log it.

Upgrades, downgrades, trials, and grace periods

Most entitlement problems show up during change: a customer upgrades mid-cycle, a card fails, or a trial ends on a weekend. If the rules are vague, support ends up guessing and engineering gets pulled in.

For upgrades, keep it simple: access should usually change immediately, while money details stay in billing. Your entitlements model should listen for a billing event like “plan changed” and apply the new plan entitlements right away. If billing does proration, great, but don’t bake proration math into entitlements.

Downgrades are where surprises happen. Pick a clear downgrade behavior and make it visible to support:

• Grace period: keep higher access until the end of the paid term.
• Read-only: allow viewing/exporting data but block new writes.
• Hard stop: block the feature immediately (best reserved for risky features).
• Over-limit behavior: allow use, but block creation once the customer is above quota.
• Data retention: keep data but disable access until upgraded.

Trials work best as their own plan, not a boolean on the customer. Give the trial plan explicit flags and limits, plus an auto-expire rule. When the trial ends, move the customer to a default plan (often “Free”) and apply the downgrade behavior you defined.

Grace periods are also useful for billing failures. A short “past due” window (for example, 3 to 7 days) gives teams time to fix payment without losing access mid-workday. Treat the grace period as a time-bound override, not a custom plan name.

One practical tip: don’t tie entitlements to marketing tier names like “Pro” or “Enterprise.” Keep stable internal plan IDs (like plan_basic_v2) so you can rename tiers without breaking rules.

Auditability and safety controls

If support can change access without engineering, you need a paper trail. A good entitlements model treats every change as a recorded decision, not a silent tweak.

For every override, capture the actor, the business reason, and timestamps. If your org needs it, add an approval step for sensitive changes.

What to record for every change

Keep the log simple so it’s actually used:

• created_by and created_at
• approved_by and approved_at (optional)
• reason (short text like “paid add-on” or “incident credit”)
• previous_value and new_value
• expires_at

Safety controls stop accidents before they reach production. Put guardrails in the admin UI and in the database: cap maximum values, block negative numbers, and require an expiry date when a change is large (for example, raising API calls 10x).

Rollback and audit readiness

Support will make mistakes. Give them a single “revert to plan defaults” action that clears customer-level overrides and returns the account to the assigned plan.

For audits, make history easy to export by customer and date range. A basic CSV export that includes reason and approver answers most questions without pulling in engineering.

Example: a customer on “Pro” needs 30 extra seats for a one-week event. Support sets seats_override=60 with expires_at next Friday, adds reason “event,” and gets manager approval. After expiry, the system automatically returns to 30, and the full trail is available if billing disputes it later.

Common mistakes that make entitlements painful

The fastest way to break an entitlements model is to let it grow accidentally. A few early shortcuts can turn into months of support tickets and “why can this customer do that?” firefighting.

One common issue is scattering feature checks everywhere. If different parts of the app decide access in different ways, you’ll ship contradictions. Centralize entitlement evaluation behind one function or service, and make every UI and API call use it.

Another frequent trap is mixing billing state with access. “Paid” is not the same as “allowed.” Billing has retries, chargebacks, trials, and invoices that settle later. Keep billing events separate, and translate them into entitlements with clear rules (including grace periods) so edge cases don’t lock users out or let them in forever.

Avoid relying on a single “tier” string like “basic” or “pro” as your only source of truth. Tiers change over time, and exceptions happen. Store explicit flags and limits so support can grant one capability without accidentally granting everything that comes with a tier label.

Manual overrides are necessary, but unlimited overrides without guardrails become invisible debt. Require an owner, a reason, and a ticket reference. Encourage expiry dates or review dates. Keep overrides narrow (one key at a time), and make them easy to audit.

Quotas also go wrong when reset rules are fuzzy. Define what “per month” means (calendar month vs rolling 30 days), what happens on upgrade, and whether unused quota carries over. Enforce these rules in backend logic, not just the UI, so support changes don’t create inconsistent behavior across web and mobile.

Quick checklist before you ship

Before you roll out an entitlements model, do a last pass with the people who’ll use it every day: support, success, and whoever is on call.

Make sure every feature maps to one stable entitlement key with a clear owner. Avoid duplicates like reports_enabled vs reporting_enabled. Ensure each plan has explicit defaults for the keys you ship. If a key is missing, fail safe (usually deny access) and alert internally so it gets fixed.

For operations, confirm the workflow is actually usable:

• Support can view effective access (plan default plus override) without SQL.
• Overrides are logged with who changed what, why, and when it expires.
• Quotas have a visible reset rule and a clear way to show current usage.

A reality test: ask support to grant a 14-day add-on to a single customer, then remove it. If they can do it confidently in under two minutes, you’re close.

Example scenario: tiers with a temporary exception

Imagine you offer three tiers, and each tier sets a few clear entitlements that show up in the product and are enforced on the backend.

• Free: 1 project, 3 users, 200 exports/month, basic API rate limit, 7-day audit logs.
• Team: 10 projects, 25 users, 2,000 exports/month, higher API rate limit, 30-day audit logs.
• Business: unlimited projects, 200 users, 10,000 exports/month, highest API rate limit, 180-day audit logs, SSO enabled.

Now a Team customer says: “We have an end-of-quarter push and need 8,000 exports this month. Can you help for 30 days?” This is exactly where a temporary override is better than moving them to a new plan.

Support opens the customer record, adds an override like export_monthly_limit = 8000, and sets expires_at to 30 days from today. They add a note: “Approved by Alex (Sales), 30-day exception for Q4 reporting.”

From the customer’s side, two things should happen:

• The UI reflects the new limit (for example, the usage meter and the “Exports remaining” label update).
• Exports keep working until they hit 8,000 for the month.

If they go over, they see a clear message like: “Export limit reached (8,000/month). Contact support or upgrade to increase your limit.”

After the expiry date, the override stops applying automatically, and the customer falls back to the Team plan limit without anyone needing to remember to switch it off.

Next steps: implement and iterate without slowing support

Start by turning “features” into a small entitlement catalog. Give each item a clear key, a type (flag vs limit vs quota), and a default value per plan. This catalog becomes shared language between product, support, and engineering, so keep names specific and stable.

Decide where enforcement lives. A safe rule is: enforce in the API for anything that changes data or costs money, use background jobs to stop long-running work when limits are exceeded, and treat the UI as guidance (disabled buttons, helpful messaging) but not the only gate.

Keep the first version tight. Focus on the entitlements that generate the most questions, add checks to the highest-risk actions, and ship an admin view that shows customer, plan, overrides, and history in one place.

If you want to build the admin panel and the underlying logic quickly without hand-coding, AppMaster (appmaster.io) is a practical fit for this kind of work: you can model plans and overrides as data, implement checks as business processes, and ship a support UI that stays consistent across backend and apps.