Entitlements

Entitlements let you map the features of your SaaS to your pricing plans. Use them to model feature flags, tier limits, and other plan-driven configuration without changing your application code every time the pricing changes.

A typical entitlement answers a question your application asks at runtime, such as:

• Is "advanced analytics" enabled for this customer?
• How many seats can this customer provision?
• Which feature tier is this customer on?
• Until when does this customer keep grandfathered access to feature X?

The Three Layers

Entitlements live in three layers, from broad to specific:

1. Library — the catalog of entitlement definitions for your tenant. Each entry has a stable slug, a type, an optional library-wide default value, and (for enums) a list of options.
2. Plan default — when an entitlement is attached to a plan, the plan can set its own default value, overriding the library default for every customer on that plan.
3. Customer override — for a specific customer, you can override the value (e.g. grant Acme Corp 50 seats on the standard 10-seat plan).

Value Precedence

For any customer + entitlement, the effective value is resolved in this order:

customer override  →  plan default  →  library default

Every API response that exposes an entitlement value also returns a value_source field — override, product, or default — so you always know which layer the value came from.

Supported Types

Type	Format	Example
boolean	true or false	true
number	Integer or decimal, at most 5 decimal places. Send it as a JSON number, not a string	25
date	YYYY-MM-DD (stored as a plain timezone-agnostic string)	"2026-12-31"
datetime	YYYY-MM-DDTHH:MM:SSZ (UTC required)	"2026-12-31T23:59:00Z"
enum	One of the option value strings defined on the entitlement	"pro"

date values are stored verbatim as YYYY-MM-DD strings with no timezone associated. Your application is responsible for interpreting the date in whatever timezone makes sense for your business logic (for example, treating "2026-12-31" as end-of-day in the customer's local timezone before comparing it to now()). If you need an exact moment in time, use datetime instead.

Common Use Cases

• Feature flags — boolean entitlements like advanced_analytics, priority_support, sso_enabled.
• Tier limits — number entitlements like max_seats, max_projects, monthly_api_calls_limit.
• Tier discriminator — an enum like feature_tier with values basic, pro, enterprise so your app can branch on a single key.
• Grandfathered features — date or datetime entitlements like legacy_feature_until to keep specific customers on old behavior with a known sunset date.

What Entitlements Are NOT

• Not billable. Entitlements are configuration, not charges. They never appear on invoices and do not produce charge records.
• Not metered usage. If you need to bill per use, model it as a service and item — see Services & Items and the Charging API.
• Not surfaced by PortaAIM to your end customers. PortaAIM has no end-user portal — entitlements are read by your SaaS via the API. It's up to your product to decide what to show, hide, or gate based on each customer's effective values.

Slug Rules

Every entitlement is identified by a slug — a short, machine-safe string used in API paths and as the stable key your code reads.

• Allowed characters: lowercase a–z, digits 0–9, and underscore _.
• Length: 1–32 characters.
• The slug is immutable after creation. Pick something stable.
• The _sys_ prefix is reserved for future system-managed entitlements and is rejected on create.

Where to Go Next

• Configure entitlements in the admin UI — see the Entitlements guide.
• Use entitlements from your code — see the Entitlements API reference.