Features and Entitlements

Features represent the capabilities you bundle with your products — things like “SSO enabled”, “Premium support”, or “100GB storage”. When customers subscribe to a plan, they automatically receive entitlements that grant access to these features.

How it works

Create features for your product, in the dashboard or through the API
Link features to prices and add those prices to a plan
Customers subscribe and entitlements are provisioned automatically
Check entitlements through the API to gate access in your application

Feature types

Boolean

Simple on/off access. Either the customer has it or they don’t.Examples: SSO enabled, Premium support, API access

Static

Fixed capability with configuration values that define limits or quotas.Examples: 25 team seats, 100GB storage, 1000 API calls/month

Metered

Usage-based access enforced against real consumption data. The customer’s balance decreases as they use your product.Examples: 1M tokens/month, 100 API calls/day, 50GB storage

Creating features

You can create features in the dashboard or through the API.

Dashboard
API

Navigate to your product

Go to Products and select the product you want to add features to.

Open the Features tab

Select the Features tab to view and manage features for this product.

Create a new feature

Select New Feature and fill in the details:

Name: Display name shown in the UI (e.g., “AI Tokens”)
Key: Identifier used in API calls, unique within the product (e.g., ai-tokens)
Type: Boolean, Static, or Metered

Save the feature

Select Save to create the feature. It’s now available to link to prices.

cURL

curl -X POST "https://api.sandbox.paygentic.io/v0/features" \
  -H "Authorization: Bearer sk_test_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "ai-tokens",
    "name": "AI Tokens",
    "type": "metered",
    "merchantId": "org_abc123",
    "productId": "prod_xyz789"
  }'

Field	Required	Description
`key`	Yes	Unique within the product. Lowercase letters, numbers and hyphens, for example `ai-tokens`
`name`	Yes	Display name
`type`	No	`boolean`, `static`, or `metered` (default: `boolean`)
`merchantId`	Yes	Your organization ID (`org_...`)
`productId`	Yes	The product this feature belongs to

A key that already exists in the product returns 409 Conflict.

Use descriptive, consistent keys for your features. They’ll appear in API responses and your application code.

Linking features to prices

Each price can carry one feature, with an entitlement template that sets what a subscriber receives. When the price is part of a plan, every subscription to that plan gets an entitlement built from the template.

Dashboard
API

Navigate to a plan

Go to Products, select the product, open the Plans tab, and select the plan you want to configure.

Edit a price

Select a price within the plan to edit its configuration.

Select a feature

Select a feature from the dropdown to associate with this price.

Configure the entitlement template

Enter the values that the subscriber receives. The template depends on the feature type, as described below.

Send feature when you create or update a price:

cURL

curl -X POST "https://api.sandbox.paygentic.io/v0/prices" \
  -H "Authorization: Bearer sk_test_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "billableMetricId": "bm_abc123",
    "model": "standard",
    "invoiceDisplayName": "AI tokens",
    "paymentTerm": "in_arrears",
    "properties": { "unitPrice": "0" },
    "feature": {
      "featureId": "feat_abc123",
      "entitlementTemplate": {
        "usagePeriod": { "interval": "P1M" },
        "issueAfterReset": 1000000,
        "isSoftLimit": false
      }
    }
  }'

Then add the price to a plan. See Plans.

Entitlement templates

Boolean features need no values. Omit entitlementTemplate. Static features take the configuration values you want your application to read, as a flat object:

{
  "maxUsers": 25,
  "storageGB": 100
}

Metered features take the grant rules:

{
  "usagePeriod": { "interval": "P1M" },
  "issueAfterReset": 1000000,
  "isSoftLimit": false
}

This grants 1,000,000 units at the start of each monthly usage period, measured by the billable metric of the price. usagePeriod.interval is an ISO 8601 duration, for example P1D, P1W, or P1M. Omit usagePeriod for a one-time grant that doesn’t refill.

issueAfterReset is the amount the customer receives. A metered feature with no template, or with a template that omits issueAfterReset, gets no grant: the balance stays at 0 and a hard limit denies access. A field the template does not support, such as limit, is ignored.

See Metered entitlements for rollover, overage, and the other template fields. To give a boolean or static feature without charging for it, link it to a fee with a unit price of 0. A metered feature needs a price that has a billable metric, because the metric measures the usage — use a unit price of 0 on that price when you don’t want to charge per unit.

Automatic entitlement provisioning

When a customer subscribes to a plan, entitlements are automatically provisioned based on the features linked to that plan’s prices. When the subscription is terminated, they are canceled. No manual intervention required. You can also issue an entitlement to a customer directly with POST /v1/entitlements.

Existing active subscriptions do not automatically pick up features you add to (or remove from) a plan after the fact. To converge them to the plan’s current shape, use Reconciling subscription features.

Checking entitlements via API

Use the API to check if a customer has access to specific features. This is how you gate functionality in your application.

API Reference: See the List Entitlements API endpoint for complete request and response schemas.

List customer entitlements

GET /v1/entitlements returns a customer’s entitlements, newest first. Identify the customer with customerId, or with externalCustomerId. Also send merchantId when your API key has access to more than one merchant. To check one feature, send productId and featureKey together. Feature keys are unique only within a product, so featureKey without productId returns 400 Bad Request.

async function hasFeature(customerId, productId, featureKey) {
  const url = new URL('https://api.sandbox.paygentic.io/v1/entitlements');
  url.searchParams.set('customerId', customerId);
  url.searchParams.set('productId', productId);
  url.searchParams.set('featureKey', featureKey);

  const response = await fetch(url, {
    headers: { 'Authorization': 'Bearer sk_test_YOUR_API_KEY' }
  });
  if (!response.ok) {
    throw new Error(`Entitlement check failed: ${response.status}`);
  }
  const { data } = await response.json();
  return data.some((e) => e.hasAccess);
}

// Example: Check if customer has SSO access
const hasSso = await hasFeature('cus_abc123', 'prod_xyz789', 'sso-access');

curl -X GET "https://api.sandbox.paygentic.io/v1/entitlements?customerId=cus_abc123&productId=prod_xyz789&featureKey=sso-access" \
  -H "Authorization: Bearer sk_test_YOUR_API_KEY"

import requests

def has_feature(customer_id, product_id, feature_key):
    response = requests.get(
        "https://api.sandbox.paygentic.io/v1/entitlements",
        params={
            "customerId": customer_id,
            "productId": product_id,
            "featureKey": feature_key,
        },
        headers={"Authorization": "Bearer sk_test_YOUR_API_KEY"},
    )
    response.raise_for_status()
    return any(e["hasAccess"] for e in response.json()["data"])

# Example: Check if customer has SSO access
has_sso = has_feature("cus_abc123", "prod_xyz789", "sso-access")

The list also returns expired and canceled entitlements, for example from an earlier subscription. Check hasAccess on the items rather than taking the first one. A page holds up to limit entitlements (default 10, maximum 100). Use offset to read the next page. An unknown customer returns 403 Forbidden, not 404, so the API doesn’t reveal which IDs exist. Response (without the productId and featureKey filters):

{
  "object": "list",
  "data": [
    {
      "entitlementId": "ent_abc123",
      "customerId": "cus_abc123",
      "featureId": "feat_sso123",
      "featureKey": "sso-access",
      "featureType": "boolean",
      "productId": "prod_xyz789",
      "subscriptionId": "sub_abc123",
      "status": "active",
      "activeFrom": "2024-01-01T00:00:00Z",
      "activeTo": null,
      "hasAccess": true,
      "metadata": {},
      "config": null
    },
    {
      "entitlementId": "ent_def456",
      "customerId": "cus_abc123",
      "featureId": "feat_sto456",
      "featureKey": "storage-quota",
      "featureType": "static",
      "productId": "prod_xyz789",
      "subscriptionId": "sub_abc123",
      "status": "active",
      "activeFrom": "2024-01-01T00:00:00Z",
      "activeTo": null,
      "hasAccess": true,
      "metadata": {},
      "config": {
        "limitGB": 500
      }
    },
    {
      "entitlementId": "ent_ghi789",
      "customerId": "cus_abc123",
      "featureId": "feat_tok789",
      "featureKey": "ai-tokens",
      "featureType": "metered",
      "productId": "prod_xyz789",
      "subscriptionId": "sub_abc123",
      "status": "active",
      "activeFrom": "2024-01-01T00:00:00Z",
      "activeTo": null,
      "hasAccess": true,
      "metadata": {},
      "config": null,
      "balance": 450000,
      "usageInPeriod": 550000,
      "overage": 0,
      "isSoftLimit": false,
      "pricingUnitId": null,
      "currentPeriodStart": "2024-02-01T00:00:00Z",
      "currentPeriodEnd": "2024-03-01T00:00:00Z"
    }
  ],
  "pagination": {
    "limit": 10,
    "offset": 0,
    "total": 3
  }
}

Key response fields

Field	Description
`hasAccess`	Whether the customer currently has access to this feature. See Hard limits vs soft limits for metered features
`featureKey`	The feature’s key, unique within its product
`featureType`	`boolean`, `static`, or `metered`
`config`	For static features, the configuration values from the entitlement template. `null` for boolean and metered features
`status`	`active`, `expired`, or `canceled`
`balance`	Metered only. Amount remaining in the current period
`usageInPeriod`	Metered only. Amount consumed so far this period
`overage`	Metered only. Usage beyond the balance
`isSoftLimit`	Metered only. `true` when access continues after the balance reaches 0
`pricingUnitId`	Metered only. The credit pool’s pricing unit, or `null`. When set, the balance fields are shared credits (see below)
`currentPeriodStart` / `currentPeriodEnd`	Metered only. The usage period the balance describes. `null` for a one-time grant (no `usagePeriod`). Before the entitlement activates, they span from the subscription start to `activeFrom`

When pricingUnitId is set, balance, usageInPeriod, and overage are in that pricing unit’s credits, and they describe the pool that every feature on the same unit shares — not the usage of this one feature. When pricingUnitId is null, they’re in the feature’s metered units. The list returns the balance fields on each metered entitlement, so one request gives you access and balance for every feature on the page. Use GET /v1/entitlements/{entitlementId} when you hold an entitlement ID and want one entitlement.

Metered features

Metered features enforce usage-based quotas against real consumption data. Instead of a static config value, the system tracks how much the customer has actually used and compares it against their granted balance.

How metered entitlements work

You configure a feature with type: metered and link it to a price with a billable metric
The entitlement template sets the grant, for example issueAfterReset: 1000000 each P1M usage period
As the customer sends meter events, their usage accumulates
Your application reads the entitlement balance before each operation, from the list or from the single-entitlement endpoint

The balance is calculated from aggregated meter data when you request it. Paygentic processes meter events asynchronously after it accepts them, so an event you just sent can take a short time to count.

Checking a metered entitlement balance

Both entitlement endpoints return the balance of a metered entitlement. GET /v1/entitlements?customerId=...&productId=...&featureKey=... returns it without an entitlement ID. GET /v1/entitlements/{entitlementId} returns one entitlement when you hold its ID. The examples below use the single-entitlement endpoint.

curl -X GET "https://api.sandbox.paygentic.io/v1/entitlements/ent_abc123" \
  -H "Authorization: Bearer sk_test_YOUR_API_KEY"

const response = await fetch(
  'https://api.sandbox.paygentic.io/v1/entitlements/ent_abc123',
  { headers: { 'Authorization': 'Bearer sk_test_YOUR_API_KEY' } }
);
if (!response.ok) {
  throw new Error(`Entitlement check failed: ${response.status}`);
}
const entitlement = await response.json();

if (!entitlement.hasAccess) {
  return { error: 'quota_exceeded', remaining: 0 };
}

// Proceed — customer has quota remaining
console.log(`Remaining: ${entitlement.balance} units`);

import requests

response = requests.get(
    "https://api.sandbox.paygentic.io/v1/entitlements/ent_abc123",
    headers={"Authorization": "Bearer sk_test_YOUR_API_KEY"},
)
response.raise_for_status()
entitlement = response.json()

if not entitlement["hasAccess"]:
    raise Exception("Quota exceeded")

An unknown entitlement ID returns 403 Forbidden, not 404. Response:

{
  "object": "entitlement",
  "id": "ent_abc123",
  "customerId": "cus_xyz789",
  "featureId": "feat_789",
  "featureKey": "ai-tokens",
  "featureType": "metered",
  "productId": "prod_xyz789",
  "subscriptionId": "sub_abc",
  "status": "active",
  "activeFrom": "2026-01-01T00:00:00Z",
  "activeTo": null,
  "hasAccess": true,
  "metadata": {},
  "config": null,
  "balance": 450000,
  "usageInPeriod": 550000,
  "overage": 0,
  "isSoftLimit": false,
  "pricingUnitId": null,
  "currentPeriodStart": "2026-02-01T00:00:00Z",
  "currentPeriodEnd": "2026-03-01T00:00:00Z"
}

Field	Description
`id`	The entitlement ID
`featureKey`	The feature’s key, unique within its product
`featureType`	Always `"metered"` for metered features
`status`	Entitlement status: `active`, `expired`, or `canceled`
`hasAccess`	`true` when the entitlement is `active`, inside its `activeFrom`–`activeTo` window, and either `isSoftLimit` is `true` or `balance` is greater than 0
`balance`	Amount remaining in the current period
`usageInPeriod`	Amount consumed so far this period
`overage`	Usage beyond the balance. It is invoiced only when `isSoftLimit` is `true`
`isSoftLimit`	Whether access continues after the balance reaches 0
`pricingUnitId`	The credit pool’s pricing unit, or `null`. When set, the balance fields are shared credits
`currentPeriodStart` / `currentPeriodEnd`	The usage period the balance describes. `null` for a one-time grant

Hard limits vs soft limits

By default, an entitlement is a hard limit: hasAccess becomes false once balance reaches 0. Set isSoftLimit: true in the entitlement template to make it a soft limit. A soft limit keeps hasAccess: true after the balance reaches 0, and the usage beyond the balance is charged as overage at the price’s per-unit rate. Paygentic doesn’t block meter events in either case. Your application enforces a hard limit by checking hasAccess before it serves the request. Use soft limits when you want to bill overage instead of blocking the customer at the quota boundary.

Required setup

For a metered feature to work, your price must be linked to a billable metric with an eventType and an aggregation. Value aggregations (SUM, AVG, MIN, MAX, LATEST) also need a valueProperty. The grant engine uses these fields to query the meter data and calculate current usage. See Meter Events for how to instrument your application to send usage data.

Use cases

Feature gating

Check hasAccess before enabling premium features in your application:

if (await hasFeature(customerId, 'prod_xyz789', 'sso-access')) {
  // Enable SSO login option
  showSsoButton();
} else {
  // Show upgrade prompt
  showUpgradePrompt('SSO is available on Professional plans and above');
}

Enforcing static limits

Read config values for static features to enforce limits:

async function getEntitlement(customerId, productId, featureKey) {
  const url = new URL('https://api.sandbox.paygentic.io/v1/entitlements');
  url.searchParams.set('customerId', customerId);
  url.searchParams.set('productId', productId);
  url.searchParams.set('featureKey', featureKey);

  const response = await fetch(url, {
    headers: { 'Authorization': `Bearer ${API_KEY}` }
  });
  if (!response.ok) {
    throw new Error(`Entitlement check failed: ${response.status}`);
  }
  const { data } = await response.json();
  return data.find((e) => e.hasAccess) ?? null;
}

const storage = await getEntitlement(customerId, 'prod_xyz789', 'storage-quota');

if (storage) {
  const limitGB = storage.config.limitGB;
  const currentUsageGB = await getCurrentStorageUsage(customerId);

  if (currentUsageGB >= limitGB) {
    throw new Error(`Storage limit of ${limitGB}GB reached`);
  }
}

Enforcing metered quotas

Read the balance before allowing consumption. With getEntitlement from the previous example, one request returns the entitlement you need, with its balance:

// Before processing an AI inference request
const tokens = await getEntitlement(customerId, 'prod_xyz789', 'ai-tokens');
if (!tokens) {
  return res.status(429).json({ error: 'Token quota exceeded' });
}

// Process the request, then send a meter event
await processInference(request);
await fetch('https://api.sandbox.paygentic.io/v0/events', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    type: 'ai.inference',
    source: 'my-app',
    subject: customerId,
    data: { tokens: 1500 }
  })
});

type must match the eventType of the billable metric. See Meter Events for the full event format.

Next steps

Meter Events — Send usage data that powers metered entitlements
Metered entitlements — Grant rules, rollover, and overage
Billable Metrics — Configure how meter events are aggregated
Customer Lifecycle — Creating subscriptions that provision entitlements
Plans — Configure pricing plans
Prices — Set up prices with features

Getting Started

Authentication

Platform

Integrations

Legal

Features and Entitlements

How it works

Feature types

Boolean

Static

Metered

Creating features

Linking features to prices

Entitlement templates

Automatic entitlement provisioning

Checking entitlements via API

List customer entitlements

Key response fields

Metered features

How metered entitlements work

Checking a metered entitlement balance

Hard limits vs soft limits

Required setup

Use cases

Feature gating

Enforcing static limits

Enforcing metered quotas

Next steps

​How it works

​Feature types

Boolean

Static

Metered

​Creating features

​Linking features to prices

​Entitlement templates

​Automatic entitlement provisioning

​Checking entitlements via API

​List customer entitlements

​Key response fields

​Metered features

​How metered entitlements work

​Checking a metered entitlement balance

​Hard limits vs soft limits

​Required setup

​Use cases

​Feature gating

​Enforcing static limits

​Enforcing metered quotas

​Next steps

How it works

Feature types

Creating features

Linking features to prices

Entitlement templates

Automatic entitlement provisioning

Checking entitlements via API

List customer entitlements

Key response fields

Metered features

How metered entitlements work

Checking a metered entitlement balance

Hard limits vs soft limits

Required setup

Use cases

Feature gating

Enforcing static limits

Enforcing metered quotas

Next steps