Understand Entitlements

BETA

This feature is currently in beta and may change over time. During the beta period, functionality, availability, and performance may vary.

To join the Beta program, request Beta access.

Entitlements define the access rights, usage limits, and service levels customers receive through their subscriptions. Use entitlements to create a reliable subscription record that supports product access, pricing tier differences, and integration-driven access control.

Why use entitlements

Use entitlements when you need a single, authoritative answer to the question: what has this subscriber been granted? Entitlements let you:

• Track access rights, usage limits, and service levels per subscription.
• Give your integrations a stable, machine-readable record of each subscriber’s allowances for access control checks.
• Vary allowances across pricing tiers by configuring different values per price point.

How entitlements work

The entitlements system uses a three-layer architecture to manage what your customers can do:

1. Features - Create features in your catalog to represent specific rights or allowances.
2. Feature entitlements - Link these features to your Plans or Products to define the default allowances. Each attachment is called a feature catalog item and stores the specific value a subscriber receives.
3. Subscription entitlements - View the entitlements automatically created for each subscription.

Key concepts

Entitlements are built from reusable features, Plan or Product assignments, and subscription-level records. Understanding these terms helps you configure entitlement values consistently and interpret what appears on a subscription.

Features

Features are the individual capabilities or limits you want to track. You define them once in your feature catalog and reuse them across any Plan or Product. Each feature has a display name, a stable, unique key used in API responses (which cannot be changed after creation), a kind, and a value type (Text, Boolean, or Numeric).

Feature kinds

Feature kinds determine whether a value represents access, a usage allowance, or a service level. Choose the kind that matches how the subscriber receives or consumes the capability.

Defaults and price point overrides

The value you set when attaching a feature to a Plan or Product becomes its default entitlement, inherited by all of that Plan’s or Product’s price points unless a specific price point overrides it. This means a single Plan or Product can carry different entitlements across its array of price points, for example, an annual plan can grant more entitlements than a monthly plan.

Because custom price points carry their own entitlement values, they effectively enable subscription-level overrides: create a custom price point for a specific customer to grant them customized entitlements. This is a strong fit for sales-led go-to-market motions, where individual deals are negotiated with their own allowances.

Product entitlements

For quantity-based Products, the entitlement value reflects what a single unit of the Product grants. If a subscriber allocates multiple units, the resolved entitlement on the subscription aggregates accordingly. For subscriptions with multiple Products, the values shown on the subscription are the aggregated result across all active Products.

How entitlements interact with billing and subscriptions

Entitlements are resolved automatically when a subscription is created, and updated whenever a subscription changes Plan, price point, or Product allocation. When a subscription event occurs (creation, Plan change, Product allocation, renewal), Advanced Billing:

1. Reads the current price point for the Plan and each allocated Product.
2. Reads the entitlement values configured on each price point.
3. Writes a stable snapshot of entitlements onto the subscription.

The snapshot remains unchanged until the next lifecycle event. A subscription’s entitlements are static between Plan and price point changes. They do not reset on the billing cycle. Editing a feature’s catalog values after a subscription is created does not retroactively change the subscription’s entitlements.

When you change a price point’s entitlement values, you’re presented with a choice: update existing subscriptions on that price point, or leave them as-is. Confirming Propagate to existing subscriptions enqueues a background job that re-resolves entitlements for all affected subscriptions.

Example: a monthly API call limit

Suppose you offer a usage limit called “API Calls per Month.” It lives once in your feature catalog, under the stable key api_calls_per_month with a monthly reset period. Attached to one of your Plans, it grants 10,000 calls by default across the Plan’s price points. On the annual price point, you’ve overridden that default with a higher allowance. A customer on the monthly plan is therefore entitled to 10,000 calls, while a customer on the annual plan receives the larger amount, each resolved automatically onto their subscription and visible on its Entitlements tab. Your application never needs to know which plan a customer chose: it reads the resolved value from the entitlements API, keyed by usage.api_calls_per_month, for its access control checks.

Requirements, dependencies, and limitations

Review these requirements and limitations before using entitlements in production. They affect when entitlements appear, how updates apply to existing subscriptions, and which subscription states return active entitlement records.

• Entitlements must be enabled for your site before you can configure or view them. Contact your Customer Success Manager or Maxio Support to request activation.
• Changes to a price point’s entitlement values apply to new subscriptions on that price point. For existing subscriptions, you choose whether to update them or leave them as-is when you save the change.
• Propagation runs as a background job. Large subscriber bases may take several minutes to fully update.
• Entitlements are returned for active or trialing subscriptions. Cancelled subscriptions return no active entitlements.
• A Product’s entitlements apply only when the Product is allocated (quantity greater than 0) on the subscription.
• A feature’s kind cannot be changed once it’s attached to a Plan or Product, the same as its key.

Related information

See Configure Entitlements to set up features, attach them to Plans and Products, and configure price point entitlement values.

See View and Update Subscription Entitlements to review resolved entitlement values on subscriptions and update existing subscriptions after entitlement changes.

See Read Subscription Entitlements with the API to retrieve resolved entitlement values for application access control and feature gating.

See Troubleshoot Entitlements to resolve missing, outdated, or unexpected entitlement values.