Skip to main content
Entitlements are the bridge between your pricing models and your application’s logic. They represent what a customer is allowed to do based on their active subscription.

​
The Entitlement Flow

  1. Subscription: A customer subscribes to a specific Plan Version.
  2. Entitlements Generated: Unprice automatically extracts the features and limits from that Plan Version and assigns them to the customer as entitlements.
  3. Verification: Your application uses the Unprice SDK to check if a customer has the required entitlement before performing an action.

​
Features vs. Entitlements

It’s helpful to think of the distinction this way:
  • Features are what you sell.
  • Entitlements are what the customer has.
For example, if you have a feature called “Monthly Exports” with a limit of 100, a subscribed customer has an Entitlement to perform “Monthly Exports” with a remaining balance of 100.

​
Types of Checks

Using the Unprice SDK, you can perform different types of entitlement checks:

​
1. Access & Usage Check (Can)

Check if a customer has access to a feature, and optionally check if they have enough balance for a specific amount of usage. Why check usage in can? Checking usage before performing an action (and before reporting it) allows you to fail gracefully without creating negative usage or partial transactions if the customer is over their limit. 
const { result, error } = await unprice.customers.can({
  customerId: "cust_123",
  featureSlug: "ai-generations",
  usage: 5 // Check if customer can consume 5 units
});

if (result?.allowed) {
  // 1. Perform the expensive operation
  // 2. Then report the usage (see below)
}

​
2. Report & Verify (Atomic)

Report usage and verify access in a single atomic call. This is the most common way to track metered features. 
const { result, error } = await unprice.customers.reportUsage({
  customerId: "cust_123",
  featureSlug: "api-requests",
  usage: 30,
  idempotenceKey: "unique-uuid-here"
});

if (result?.allowed) {
  // Process the request
} else {
  // Return "Limit reached" error
}

​
Benefits of the Entitlement System

  • Decoupling: Your code doesn’t need to know about “Gold” or “Silver” plans. It only needs to know if the customer can perform a specific action.
  • Real-time Updates: If a customer upgrades their plan, their entitlements are updated instantly across all your services.
  • Grace Periods: Unprice allows you to configure “overage” strategies, letting customers exceed their limits while you notify them to upgrade.