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 New Feature.

3. Complete the Feature Fields.

   Field	Description
   Name	The display name shown to merchants and in API responses (e.g., “API Calls per Month”).
   Lookup Key	A stable, unique identifier used in API responses (e.g., api_calls_per_month). Cannot be changed after creation.
   Kind	Controls how the feature value is interpreted. Cannot be changed once the feature is attached to a Plan or Product. See Feature kinds.
   Value type	The data type for the feature value: Text, Boolean, or Numeric.
   Unit	For usage limits only. The unit label shown alongside the value (e.g., “calls”, “GB”, “seats”).
   Default value	The value pre-filled when attaching this feature to a Plan or Product.
   Default reset period	For usage limits only. The interval and unit the limit resets on (e.g., every 1 month, every 3 hours).
   Granted units expire	For usage limits only. When a grant of units expires: never, after a set number of days, after a set number of months, or when the next refill arrives.
   Description	Optional internal context for your team.

4. Choose the kind that matches the nature of the capability.

   Kind	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

5. Click Save 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. The controls sit in a Wallet section on the feature's create and edit screen.

To back a feature with a wallet

1. While creating or editing a Limit feature, toggle Bill this feature through a wallet.
2. Optionally, enter a Wallet Name to label this wallet definition. The field can be left blank.
3. Choose the Billing product, the Wallet Product this feature settles purchases against. Only Wallet Products that already carry an active price point appear in this list; if none do, create one in Catalog > Wallet Products and give it a price point before continuing.
4. Choose the Pricing, the price point that purchases of additional units settle against.
5. Review When the balance runs out. This field is read-only and set to Hard stop, which blocks further usage once the balance reaches zero.
6. Set what happens to Usage beyond the balance: discard it, or allow the balance to go negative.

The Unit field locks to the billing product's unit on a wallet-backed feature, since the wallet is denominated in whatever the product bills in.

A wallet-backed feature is also refilled automatically on its own recurring schedule, independently of any manual purchase. That automatic refill keeps running for as long as the subscription is still being invoiced for the period it covers, which includes a subscription that's Past Due, in a Soft Failure payment retry, or Unpaid after dunning, not only one that's Active or Trialing.

Refills stop when the subscription reaches a state that no longer advances the billing period, either one where billing is temporarily halted, such as Suspended, Paused, or On Hold, or one where it has ended, such as Canceled, Expired, or Trial Ended. None of these stops are permanent. If the subscription later returns to a state that grants, for example after you reactivate it, the refill schedule re-arms and funding resumes automatically.

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.

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.

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.

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.

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