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 Check

Check if a customer has access to a feature before doing work. Why check access first? Checking before performing an action lets you fail gracefully when the customer is not entitled to the feature. 
const { result, error } = await unprice.entitlements.verify({
  customerId: "cust_123",
  featureSlug: "ai-generations"
});

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

​
2. Ingest & Verify (Atomic)

Ingest usage and verify access in a single call. This is the most common way to enforce metered features. 
const { result, error } = await unprice.events.ingestSync({
  idempotencyKey: "unique-uuid-here",
  eventSlug: "api_request",
  customerId: "cust_123",
  featureSlug: "api-requests",
  properties: {
    usage: 30
  }
});

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.