Entitlements

Entitlements are the plan-layer access contract for features and feature families.

This page documents the packaging rules that matter when you model plans.

Prereqs

• You use stable feature_family_code and feature_code values: Features and meters.

Entitlement model

Entitlements are an access-control layer for resources whose effective entitlement_required resolves to true.

• If effective entitlement_required=false, a plan does not need an explicit entitlement entry for that feature or family. Access can still be shaped by gate policies, bundles, budgets, and funding.
• If effective entitlement_required=true, the account needs an entitlement allow path from its effective plan state.

Each entitlement entry targets exactly one scope:

• feature_family_code
• feature_code

You can use both scopes in the same plan, but each single entry is one-or-the-other.

Effects:

• allow
• deny

Use feature_family_code for tier packaging, then use feature_code for precise exceptions.

Structural rules

• A plan can have at most one entry per (plan, feature_family) and at most one per (plan, feature).
• Entitlements are realm-local: referenced feature families and features must exist in the same realm.
• Updating plan entitlements should be treated as replacing policy state, not as mutable runtime flags in your app.

Packaging pattern

1. Start with coarse family-level allow entries for the entitlement-required resources in the plan tier.
2. Add explicit feature-level exceptions where needed.
3. Keep feature codes stable over time; evolve plan membership rather than renaming feature identifiers.
4. Keep entitlement design separate from limit design: entitlements answer access, while gate bundles/policies answer runtime limits.

Verify

For a sample billing account assigned to the plan:

• expected allowed features are accepted by authorize
• expected denied features are rejected by authorize

Next

• Limits and policies: Limits and policies