Entitlement Management | Prolifi

What this covers

This reference document covers Prolifi’s entitlement management system — what entitlements are, the four entitlement types, how they are configured and provisioned, and how to implement entitlement enforcement in your application. Entitlement management is the mechanism by which Prolifi controls what customers can access or consume based on their subscription.

Prerequisites

Before configuring entitlements:

Products exist in the product catalog — See: Product Catalog & Pricing Reference
Features have been defined at the product level
Plans exist for the relevant products
For usage-linked entitlements: usage metrics are configured — See: Getting Started: Developer

1. What Are Entitlements and How They Work

Entitlements (Glossary: Entitlement) are the structured access rights that a customer holds as a result of their subscription. They define what the customer is allowed to access or consume — not what they are charged for (that is the billing model’s domain).

1.1 Entitlements vs. billing

Billing and entitlements are separate but related:

Concept	Controls
Billing model	When and how much the customer is charged
Entitlement	What the customer can access or consume

A customer on a £100/month recurring plan may have:

An entitlement for 10 user seats
An entitlement for 100 GB of storage
An entitlement granting access to the “Advanced Reporting” feature

The billing model charges £100/month. The entitlements define what £100/month buys in terms of access. These are configured separately and serve different purposes.

1.2 How entitlements are provisioned

Entitlements are provisioned automatically when a subscription is created or when a subscription plan changes. You do not need to manually create entitlement records per customer — Prolifi creates them from the entitlement definitions attached to the subscribed plan.

Provisioning trigger events:

Subscription created — entitlements from the plan are provisioned
Subscription upgraded — new entitlements from the new plan replace or supplement existing ones
Subscription downgraded — entitlements reduced to the new plan’s definitions
Subscription renewed at period end — variable entitlements reset to their configured allocation
Subscription cancelled — entitlements expired according to configured expiry rules

1.3 Entitlement state

Each customer entitlement has a state:

State	Meaning
Active	Entitlement is accessible and has remaining balance (for variable types)
Exhausted	Variable entitlement has been fully consumed; no balance remaining
Expired	Entitlement has passed its expiry date
Paused	Subscription is paused; entitlement is temporarily inactive

1.4 The role of your application

Prolifi maintains entitlement state. Your application is responsible for enforcing that state — checking entitlement status before allowing actions that consume entitled resources and blocking access when entitlements are exhausted or expired.

The enforcement pattern:

Customer requests an action in your application (e.g., "run advanced report")
  |
Your application queries Prolifi entitlement API:
  GET /entitlements/{customer_id}/{feature_id}
  |
Prolifi returns entitlement state:
  { "state": "active", "balance": 45, "limit": 100, "resets_at": "2026-04-01" }
  |
Your application evaluates the state:
  - If state is "active" and balance > 0: allow the action, record consumption
  - If state is "exhausted" or "expired": block the action, present upgrade prompt

Prolifi does not automatically block customer actions at the application layer — it provides the authoritative state that your application uses to make the enforcement decision.

2. Variable Entitlements

A Variable Entitlement (Glossary: Variable Entitlement) has a defined quantity, and consumption is tracked and counted against that quantity.

2.1 How variable entitlements work

A plan is configured with a variable entitlement: “100 API calls per billing period”
When a customer subscribes, Prolifi creates an entitlement record: balance = 100, limit = 100
As the customer uses the API, your application records consumption events
Prolifi tracks the running balance: balance = 100 - consumed
When balance = 0, the entitlement is in the “exhausted” state
At the next billing period, the balance resets to the configured limit (unless carry-over is configured)

2.2 Consumption recording

Variable entitlements can be linked to usage events (the entitlement balance is reduced automatically when usage events are ingested) or can be decremented explicitly via the entitlement consumption API.

Option A — Linked to usage events (recommended for metered usage): Configure the entitlement to reference a usage metric. As usage events come in, the entitlement balance decreases automatically in parallel with usage aggregation.

Option B — Explicit consumption API calls (for non-usage-event consumption): Your application calls the entitlement consumption API directly when an entitled action occurs:

1 POST /entitlements/consume
2 {
3   "customer_id": "cust_abc123",
4   "feature_id": "feat_api_calls",
5   "quantity": 1,
6   "idempotency_key": "action_unique_id_456"
7 }

2.3 Low-balance alerts

Configure a low-balance threshold on variable entitlements. When the balance drops below the threshold, Prolifi emits an entitlement.low_balance webhook event that your application can use to:

Present an in-product upgrade prompt
Send a notification email to the customer
Trigger an automated upsell flow

2.4 Entitlement exhaustion

When a variable entitlement reaches zero balance, Prolifi emits an entitlement.exhausted webhook event. Your application must respond to this event to enforce the paywall:

Block access to the entitled feature
Present an upgrade prompt or a “purchase more” option
Optionally allow overage (if configured) and track the overage for billing

Overage handling: Variable entitlements can be configured to allow overage consumption beyond the limit. When overage is enabled, Prolifi tracks the amount consumed beyond the limit. The overage can be:

Billed as a usage-based charge on the next invoice
Billed as a one-off overage invoice
Subject to a predefined overage rate (which may differ from the standard per-unit rate)

3. Expirable Entitlements

An Expirable Entitlement (Glossary: Expirable Entitlement) has a defined expiry — the entitlement is only valid until a specified date or after a specified duration. After expiry, the entitlement is inaccessible regardless of whether any balance remains.

3.1 How expirable entitlements work

An expirable entitlement carries an expires_at timestamp. The expiry may be configured as:

Fixed date: The entitlement expires on a specific calendar date (e.g., December 31, 2026)
Relative to subscription start: The entitlement expires N days after the subscription was created (e.g., expires 90 days after signup)
Relative to billing period: The entitlement expires at the end of the current billing period

When the expires_at date passes, the entitlement state transitions to expired and Prolifi emits an entitlement.expired webhook event. Your application receives this event and revokes the customer’s access to the expired entitlement.

3.2 When to use expirable entitlements

Time-limited promotional access: “30 days of premium features, then downgrade to standard”
Annual feature packs: A bundle of usage credits valid for the calendar year
Limited beta access: Early access that expires at a defined date regardless of subscription status
Grace periods: Continued access for a defined period after a subscription lapses

3.3 Expiry notification

Configure advance warning of entitlement expiry. When the expires_at is within a configured warning window, Prolifi emits an entitlement.expiry_warning event. This allows your application to notify the customer before the entitlement expires rather than only after.

4. Carry-Over Entitlements

A Carry-Over Entitlement (Glossary: Carry-Over Entitlement) does not reset to zero at the end of the billing period. Instead, any unused balance is added to the next period’s allocation.

4.1 How carry-over entitlements work

At billing period renewal:

Standard reset: Entitlement resets to the configured limit (unused balance is lost)
Carry-over: Unused balance is added to the new period’s limit

Example:

Monthly limit: 100 API calls
Customer uses 60 in Month 1
Unused: 40 calls
Without carry-over: Month 2 starts at 100
With carry-over: Month 2 starts at 100 + 40 = 140

4.2 Carry-over cap

Carry-over can be configured with a cap to prevent unlimited accumulation:

Uncapped carry-over: All unused balance carries over indefinitely
Capped carry-over: A maximum carry-over amount (e.g., no more than one period’s worth of carry-over)
Percentage carry-over: Only a percentage of unused balance carries over (e.g., 50% of unused balance)

4.3 When to use carry-over entitlements

Fairness model: Customers who pay for a capacity but cannot use it in a given month feel they are getting value if unused capacity carries forward
Consumption smoothing: Customers with irregular usage patterns (heavy one month, light the next) benefit from carry-over
Promotional allowances: Bonus credits issued as a promotion that the customer can use at their pace

5. Auto-Extension Entitlements

An Auto-Extension Entitlement (Glossary: Auto-Extension Entitlement) automatically extends its expiry date when it would otherwise expire, without requiring any customer action.

5.1 How auto-extension works

Auto-extension applies to expirable entitlements that are configured with the auto-extension option. When the expires_at date is reached:

Standard behaviour: Entitlement state transitions to expired
Auto-extension: The expires_at date is automatically advanced by the configured extension period, and the entitlement remains in the active state

Auto-extension events are logged in the entitlement audit trail and optionally surfaced via webhook.

5.2 Auto-extension configuration

Extension trigger: When the current expiry date is reached
Extension period: The duration by which to advance the expiry (e.g., extend by 30 days, extend by 1 billing period)
Maximum extensions: Whether there is a limit on how many times the entitlement can auto-extend
Extension condition: Whether auto-extension is unconditional or conditional on the subscription remaining active

5.3 When to use auto-extension

Continuous access entitlements: Entitlements that should remain accessible as long as the subscription is active, but are technically “expirable” for accounting or lifecycle management purposes
Annual entitlements with subscription lock: An annually provisioned entitlement that auto-extends each year on subscription renewal without needing to be re-provisioned

6. Entitlement Exhaustion and Paywalls

Entitlement exhaustion is a high-value moment in the customer lifecycle. When a customer’s entitlement is exhausted, they are at a natural upsell inflection point — they want to continue doing the thing the entitlement covers, which means they need to upgrade.

6.1 Paywall implementation

When your application receives an entitlement.exhausted event (or detects exhaustion via an API query), implement a paywall:

Block the action the customer was attempting to take
Present a clear, helpful paywall message explaining:
- What the customer has run out of
- What their options are (upgrade plan, purchase more credits, wait for next period reset)
Provide a direct path to upgrade (link to your upgrade flow or the customer portal)

Paywall message best practices:

Name the specific entitlement that is exhausted (not a generic “you’ve hit your limit”)
Show the customer how much they have used versus their limit
Show when the entitlement resets (if applicable)
Offer an upgrade as the primary action, with “Wait for reset” as secondary if relevant

6.2 Upgrade flow on exhaustion

When a customer clicks “Upgrade” from a paywall:

Redirect to the hosted customer portal’s plan upgrade flow, or
Surface your own upgrade flow with plan options retrieved from the Prolifi catalog API

On plan upgrade:

New entitlements are provisioned immediately for the higher-tier plan
Prolifi emits subscription.plan_changed and entitlement.updated webhook events
Your application receives these events and restores the customer’s access

6.3 Graceful degradation vs. hard stop

Configure whether your application implements:

Hard stop: The action is completely blocked when the entitlement is exhausted
Graceful degradation: The action is allowed in a reduced capacity (e.g., lower quality output) when exhausted
Overage with notification: The action is allowed but the overage is tracked and billed

The choice depends on the product experience you want to deliver and the commercial model you have configured.