Features & Limits (Entitlements) - Kelviq Documentation

Entitlements are the modern way to control feature access in your application. Instead of checking which plan a customer is on, you check which features they have access to. This fundamental shift gives you unprecedented flexibility to experiment with pricing, create custom deals, and iterate on your product—all without changing code.

For SDK installation and API reference, see:

Why Entitlements?

The Problem with Plan-Based Access

Traditional SaaS applications check access like this:

// ❌ The old way - hardcoded, brittle, requires code changes
if (user.plan === 'pro' || user.plan === 'enterprise') {
  showAdvancedAnalytics();
}

if (user.plan === 'enterprise') {
  enableSSO();
}

This approach has serious limitations:

Code changes required for any pricing restructure
Deployment needed to move a feature between plans
Engineering bottleneck for every pricing experiment
Webhook complexity to sync subscription state
Stale cache issues when plans change
Custom deals are painful requiring one-off code

The Entitlements Approach

With Kelviq, you check features directly:

// ✅ The Kelviq way - flexible, decoupled, no code changes needed
const hasAnalytics = await client.entitlements.hasAccess({
  customerId: "cust_123",
  featureId: "advanced-analytics"
});

if (hasAnalytics) {
  showAdvancedAnalytics();
}

Now you can:

Move features between plans without code changes
Create custom enterprise deals in minutes
A/B test pricing without deployments
Let Sales and Product iterate independently

How It Works

The Flow

Setup plans and features on Kelviq Dashboard
When a customer completes checkout, their entitlements are automatically assigned.
Your app checks access via SDK
Customer gets immediate access

No Webhooks Required

When a customer completes checkout:

Payment is processed
Entitlements are assigned automatically
Your app checks access via SDK
Customer gets immediate access

You don’t need to:

Build webhook handlers
Sync subscription state to your database
Handle race conditions
Manage cache invalidation

Feature Types

Kelviq supports three types of features to cover all access control scenarios.

Boolean Features

Simple on/off access control.

Use for:

Feature flags (SSO, API access, white-labeling)
Premium features (advanced analytics, custom branding)
Access gates (admin panel, beta features)

Example configuration:

Feature	Starter	Pro	Enterprise
Basic Dashboard	✓	✓	✓
Advanced Analytics	✗	✓	✓
SSO	✗	✗	✓
White Label	✗	✗	✓

Meter Features

Usage-based features with limits and tracking.

Use for:

API calls, requests, or operations
Storage (GB, files, records)
Team members or seats
Messages, emails, or notifications
AI tokens or credits

Configuration options:

Option	Description
Limit	Maximum usage allowed (or unlimited)
Reset Period	When usage resets (monthly, weekly, daily, never)
Hard Limit	Block access when limit reached
Soft Limit	Allow overages but notify/warn
Rollover	Carry unused quota to next period

Example configuration:

Feature	Starter	Pro	Enterprise
API Calls	1,000/mo	100,000/mo	Unlimited
Storage	5 GB	100 GB	1 TB
Team Members	3	25	Unlimited

Customizable Features

Dynamic values that aren’t simple on/off or numeric limits.

Use for:

Configuration values
Tier-specific settings
Dynamic feature behavior

Soft Limits vs. Hard Limits

Choose the right enforcement strategy for each feature.

Hard Limits

Block access completely when the limit is reached. Best for:

Cost-sensitive features (AI tokens, bandwidth)
Preventing abuse
Strict contractual limits

Soft Limits

Allow continued access but notify the user. Best for:

Driving upgrades without blocking users
Features where occasional overages are acceptable
Better user experience during high-usage periods

Checkout Integration

When a customer goes through checkout, entitlements are automatically assigned. The key is passing the customer ID.

Passing Customer ID

When creating a checkout session, include the customer identifier:

import { Kelviq, CHARGE_PERIOD_CHOICES } from '@kelviq/node-sdk';

const response = await client.checkout.createSession({
  planIdentifier: "plan-pro-monthly",
  chargePeriod: CHARGE_PERIOD_CHOICES.MONTHLY,
  successUrl: "https://yourapp.com/checkout/success",
  customerId: "cust_789",  // Your customer ID - recommended
});

Always pass a customerId when creating checkout sessions. If you don’t, a new customer will be created automatically, which may lead to duplicate customer records.

For complete checkout API options, see the Node SDK Documentation.

New vs. Existing Customers

Scenario	What Happens
New customer ID	Customer created automatically, entitlements assigned
Existing customer	Entitlements updated based on new purchase
Upgrade	New plan entitlements replace old ones
Downgrade	Adjusted at end of current billing period

Automatic Assignment

After successful payment:

Customer record is created/updated
Plan entitlements are assigned instantly
No webhook processing needed
Customer can access features immediately

SDK Integration

Quick Start

Install the SDK and start checking entitlements in minutes.

npm install @kelviq/node-sdk

import { Kelviq } from '@kelviq/node-sdk';

const client = new Kelviq({ 
  accessToken: process.env.KELVIQ_ACCESS_TOKEN 
});

Get your API key from Settings → Developers in the Kelviq dashboard.

Checking Feature Access

// Check boolean feature access
const hasAccess = await client.entitlements.hasAccess({
  customerId: "cust_123",
  featureId: "advanced-analytics"
});

if (hasAccess) {
  showAdvancedAnalytics();
} else {
  showUpgradePrompt();
}

Reporting Usage

For meter features, report usage after each consumption:

import { BEHAVIOUR_CHOICES } from '@kelviq/node-sdk';

// Increment usage by a value (DELTA)
await client.reporting.reportUsage({
  value: 1,
  customerId: "cust_123",
  featureId: "api-calls",
  behaviour: BEHAVIOUR_CHOICES.DELTA  // Adds to current usage
});

// Or set absolute value (SET)
await client.reporting.reportUsage({
  value: 150,
  customerId: "cust_123",
  featureId: "seats",
  behaviour: BEHAVIOUR_CHOICES.SET  // Replaces current usage
});

For complete SDK reference including all methods and parameters, see the Node SDK Documentation.

The sandbox environment is completely separate from production. Use different API keys and note that sandbox data won’t appear in production.

Managing Customer Entitlements

Viewing Customer Entitlements

In the Kelviq dashboard:

Navigate to Customers
Select a customer
View their Features section

You’ll see:

All entitled features
Current usage vs. limits
Reset dates for meters
Whether values are overridden

Overriding Entitlements

Sometimes you need to give a specific customer different access than their plan provides. Common scenarios:

Sales gave a prospect extra API calls for a POC
Customer needs temporary limit increase
VIP customer gets special access
Compensating for a service issue

To override:

Go to the customer’s detail page
Find the feature in the Features section
Click the menu (⋯) → Override usage
Set the new value
Save

Overrides are:

Per-customer (don’t affect the plan)
Marked with an override indicator
Can be reverted anytime

Resetting Usage

For meter features, you can reset a customer’s usage:

Go to the customer’s detail page
Find the meter feature
Click the menu (⋯) → Reset usage

This sets their current usage back to 0, giving them their full quota again.

Plan Inheritance

Create plan hierarchies to reduce duplication and maintain consistency.

How It Works

Enterprise Plan
    └── inherits from → Pro Plan
                            └── inherits from → Starter Plan

When you set up inheritance:

Child plan automatically gets parent’s features
You can override specific values in the child
Changes to parent propagate to children (unless overridden)

Override Indicators

Icon	Meaning
🔗 Inherited	Value comes from parent plan, stays in sync
⚡ Overridden	Value was customized, no longer syncs with parent

Use Cases

Tiered plans:

Starter: 1,000 API calls
Pro: inherits Starter + overrides API calls to 100,000 + adds analytics
Enterprise: inherits Pro + overrides to unlimited + adds SSO

Regional plans:

US Pro: standard features
EU Pro: inherits US Pro + adds GDPR compliance features

Subscription Lifecycle

What Happens During…

Successful Purchase

Entitlements assigned immediately
Customer can access features right away
No webhook handling required

Upgrade

New plan entitlements replace old ones
Happens immediately
Usage meters may reset or carry over (configurable)

Downgrade

New entitlements take effect at end of billing period
Customer keeps current access until then
Prevents mid-cycle disruption

Cancellation

Entitlements remain active until period ends
Customer can use features they paid for
Access revoked when subscription expires

Failed Payment

Grace period begins (configurable)
Customer retains access during grace period
After grace period: access revoked
Entitlements restored when payment succeeds

Refund

Entitlements revoked immediately
Customer loses access to plan features

Manage subscriptions programmatically using the Subscriptions API.

Get Started

Quickstart

Product Catalog

Checkout

Sales

Coustomers-management

Payouts

Customer-portal

Guides

Legal

​Why Entitlements?

​The Problem with Plan-Based Access

​The Entitlements Approach

​How It Works

​The Flow

​No Webhooks Required

​Feature Types

​Boolean Features

​Meter Features

​Customizable Features

​Soft Limits vs. Hard Limits

​Hard Limits

​Soft Limits

​Checkout Integration

​Passing Customer ID

​New vs. Existing Customers

​Automatic Assignment

​SDK Integration

​Quick Start

​Checking Feature Access

​Reporting Usage

​Managing Customer Entitlements

​Viewing Customer Entitlements

​Overriding Entitlements

​Resetting Usage

​Plan Inheritance

​How It Works

​Override Indicators

​Use Cases

​Subscription Lifecycle

​What Happens During…

​Successful Purchase

​Upgrade

​Downgrade

​Cancellation

​Failed Payment

​Refund

Why Entitlements?

The Problem with Plan-Based Access

The Entitlements Approach

How It Works

The Flow

No Webhooks Required

Feature Types

Boolean Features

Meter Features

Customizable Features

Soft Limits vs. Hard Limits

Hard Limits

Soft Limits

Checkout Integration

Passing Customer ID

New vs. Existing Customers

Automatic Assignment

SDK Integration

Quick Start

Checking Feature Access

Reporting Usage

Managing Customer Entitlements

Viewing Customer Entitlements

Overriding Entitlements

Resetting Usage

Plan Inheritance

How It Works

Override Indicators

Use Cases

Subscription Lifecycle

What Happens During…

Successful Purchase

Upgrade

Downgrade

Cancellation

Failed Payment

Refund