Overview The EntitlementsClient provides methods for checking and querying feature entitlements. The check() method is the core primitive of the SDK — it determines whether a customer is allowed to use a specific feature based on their plan.
Methods check() Check whether a customer has access to a specific feature. This is the most critical method in the SDK — it evaluates the customer’s plan, metered usage, and custom entitlement overrides.
const result = await revstack . entitlements . check ( customerId , featureId , options );
The customer to check. Example: "usr_abc123"
The entitlement slug or ID. Example: "api-calls" or "ent_abc123"
Optional check parameters. The amount of the entitlement to consume. Default: 1Example: 10 (for checking if customer can make 10 API calls)
The check result. Whether the customer is allowed to perform the action.
Human-readable reason if allowed is false. Example: "Limit exceeded", "Feature not available on plan"
Remaining balance after this check (for metered entitlements).
Currency of the remaining balance (for monetary entitlements).
Example: const { allowed , reason , remainingBalance } = await revstack . entitlements . check ( "usr_abc123" , "api-calls" , { amount: 10 } ); if ( ! allowed ) { throw new Error ( `Access denied: ${ reason } ` ); } console . log ( `Remaining: ${ remainingBalance } API calls` );
list() List all active entitlements for a customer, including limits from their plan and any custom overrides.
const entitlements = await revstack . entitlements . list ( customerId );
The customer whose entitlements to list. Example: "usr_abc123"
Array of entitlement definitions the customer has access to. Show Entitlement properties
Unique identifier with ent_ prefix.
Human-readable entitlement name. Example: "API Calls"
URL-safe unique slug. Example: "api-calls"
Entitlement type: boolean, metered, tiered, etc.
Unit of measurement: count, bytes, seconds, etc.
Project this entitlement belongs to.
ISO 8601 timestamp of creation.
Example: const entitlements = await revstack . entitlements . list ( "usr_abc123" ); for ( const ent of entitlements ) { console . log ( ` ${ ent . name } ( ${ ent . slug } ): ${ ent . type } ` ); }
get() Retrieve a single entitlement definition by ID.
const entitlement = await revstack . entitlements . get ( entitlementId );
The entitlement’s unique identifier. Example: "ent_abc123"
The entitlement definition.
Example: const entitlement = await revstack . entitlements . get ( "ent_abc123" ); console . log ( entitlement . name ); // "API Calls"
Common Patterns Boolean Entitlements // Check if a feature is enabled const { allowed } = await revstack . entitlements . check ( userId , "advanced-analytics" ); if ( allowed ) { // Show advanced analytics dashboard }
Metered Entitlements // Check before consuming a metered resource const { allowed , remainingBalance } = await revstack . entitlements . check ( userId , "ai-tokens" , { amount: 500 } ); if ( ! allowed ) { throw new Error ( "Insufficient tokens" ); } // Proceed with the operation await openai . chat . completions . create ({ ... }); // Report actual usage await revstack . usage . report ({ customerId: userId , featureId: "ai-tokens" , amount: 500 , });
Usage with API Rate Limiting import { RateLimitError } from "@revstackhq/node" ; async function callAPI ( userId : string ) { try { const { allowed } = await revstack . entitlements . check ( userId , "api-calls" ); if ( ! allowed ) { throw new RateLimitError ( "API rate limit exceeded" ); } // Proceed with API call return await fetch ( "https://api.example.com/data" ); } catch ( error ) { if ( error instanceof RateLimitError ) { // Handle rate limit error return { error: "Please upgrade your plan" }; } throw error ; } }
