Configure 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.

Configure entitlements in Advanced Billing to define the features, usage limits, and service levels included with each Plan, Product, and price point. Use entitlement values to keep subscription access, customer-facing limits, and API-driven integrations aligned with what each subscriber has been granted.

Configuration checklist

Before using entitlements in production, confirm the following:

• Entitlements is enabled for your site.
• Feature templates are created for each capability you want to track.
• Each feature template has the correct kind (access, limit, or service right).
• Features are attached to the relevant Plans or Products.
• Each price point has the correct entitlement values configured.
• Custom price point entitlement values have been set where pricing tiers differ.
• Entitlements appear correctly on a test subscription.
• Your integration reads entitlements from the API as expected.

Enable entitlements

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.

Once enabled, entitlement configuration options appear in the Plan and Product editors, and an Entitlements tab appears on each subscription.

Define features

Features are the individual capabilities or limits you want to track. Define them once in your feature catalog and reuse them across any Plan or Product.

To create a feature

1. Go to Catalog > Features.

2. Click Create.

3. Under Feature Type, choose Access, Limit, or Service Right. The type can't be changed once the feature is attached to a Plan or Product, and the rest of the fields only appear once a type is chosen. Choose the type that matches the nature of the capability.

   Feature Type	Use when	Example
   Access	The feature is a boolean on/off capability.	SSO integration, priority support, custom domain
   Limit	The feature is a numeric quota that resets on a cadence.	10,000 API calls per month, 50 GB storage
   Service Right	The feature defines a service level or tier that does not reset.	99.9% SLA, dedicated infrastructure, response time guarantee

4. Complete the fields for that type.

   Field	Description
   Name	The display name shown to merchants and in API responses (e.g., “API Calls per Month”). Maximum 255 characters.
   Handle	A stable identifier, unique within your site, used in API responses (e.g., api_calls_per_month). Maxio fills it in from the Name as you type, in lowercase with underscores in place of spaces and punctuation, until you edit it yourself. Accepts lowercase letters, numbers, and underscores only, and cannot be changed after creation. Maximum 255 characters.
   Value Type	Service Right only. The data type for the feature value: Boolean, Text, or Numeric.
   Unit	Limit only. The unit label shown alongside the value (e.g., “calls”, “GB”, “seats”). Maximum 255 characters.
   Default Value	The value pre-filled when attaching this feature to a Plan or Product. Not configurable for Access: an Access feature is always created enabled. Maximum 255 characters.
   Interval	Limit only. How often the limit resets: a whole number paired with Hour(s), Day(s), Week(s), Month(s), or Year(s) (e.g., every 1 month, every 3 hours).
   Grants Expiration	Limit, and only once the feature is wallet-backed. When a grant of units expires: never, after a set number of days or months, or the same as the refill interval. This control lives in the Wallet Provisioning view; see Configure a Wallet.
   Description	Optional internal context for your team.

5. Click Create Feature.

Back a feature with a wallet

If your site has wallets enabled in addition to entitlements, a Limit feature can optionally be backed by a wallet instead of a plain reset-based allowance. A wallet-backed feature draws down a running balance that's replenished by purchase, and its purchases are invoiced through a Wallet Product you've already priced, rather than resetting the allowance on a fixed cadence. A Limit feature's create and edit screen shows a Wallet Provisioning card; click Add wallet (or Edit, once added) to open the dedicated Wallet Provisioning view.

See Configure a Wallet for the full procedure, what each wallet setting controls, and how refills behave once subscriptions hold the feature.

Attach features to plans and products

Once features are defined, attach them to the Plans and Products that grant them. Each attachment is called a feature catalog item and stores the specific value a subscriber receives.

A Limit feature can't be attached to a Product that's metered, prepaid-usage, or events-based. That Product already meters its own consumption, so a usage-limit feature there, wallet-backed or not, would double it. Attaching one is refused with a 422 error code.

To attach features to Plans

1. Edit an existing Plan or create a new one.
2. Click the Entitlements tab.
3. Click Add Feature.
4. Select a feature from your catalog.
5. Enter the value granted by this Plan (e.g., 10000 for 10,000 API calls).
6. For usage limits, confirm or adjust the reset period.
7. Click Save.

The values you set here become the default entitlements for all price points on this Plan. You can override individual values per price point. See Configure price point entitlements.

An Access feature has no value to enter. Attaching it always grants it, and the Value column shows a read-only green Enabled instead of a toggle, whatever the feature's catalog default value is. If an Access feature was attached earlier with a Disabled value, the column shows a read-only red Disabled. A Limit or Service Right feature keeps an editable value.

To attach features to Products

1. Open a Product.
2. Scroll to the Entitlements card.
3. Click Add Feature.
4. Select a feature and enter a value.
5. Click Save.

A feature attached to a Product keeps the value you enter, no matter how many units a subscriber buys. Only a Limit feature attached to a quantity-based component scales with the quantity purchased: the value is what a single unit grants, and a subscriber who allocates multiple units is entitled to that value multiplied by the quantity. An attached Access feature shows the same read-only status as on a Plan.

Configure price point entitlements

Each price point inherits the default entitlement values set on the Plan or Product. You can override any value for a specific price point to reflect tiered pricing.

To override entitlements on a price point

1. Open the Plan or Product.
2. Go to Price Points and open the price point.
3. Click the Entitlements tab.
4. Check Override Default Entitlements for this Price Point.
5. Adjust any feature values as needed. An Access feature has no value to adjust here either: it shows the same read-only status as on the Plan or Product.
6. Click Save.

Changes to a price point’s entitlement values apply to new subscriptions on that price point. Existing subscriptions are not automatically updated. To update existing subscriptions, see Propagate entitlement changes.

Related information

See Understand Entitlements to learn the concepts behind features, feature kinds, and default and overridden 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.