Entitlements Overview

An entitlement is an access right a customer holds because of their subscription: a feature that is on, a quota such as seats or included storage, a named tier, or a recurring credit allocation. Entitlements are defined on plans and subscription versions alongside the prices, and your application reads them back through the API to decide what the customer can do. Use them for gating and provisioning; use billable metrics and credits for measuring and charging consumption. See How Alguna Works for where entitlements sit in the object graph.

What an entitlement is

An entitlement is a key, a type, a mode and a value, attached to a subscription version:

`type`	`value`	Use it for
`boolean`	`"true"` / `"false"`	Feature flags
`number`	An integer, as a string	Seats, quotas, included units
`string`	Free text	Access tiers, plan labels
`credit_allocation`	An allocation and a timing, not a scalar value	Included balances the customer draws down

`mode`	Behaviour
`static`	The value is fixed for the life of the subscription version
`grant_based`	The entitlement provisions grants on a schedule. Required for `credit_allocation`

A credit_allocation entitlement carries an allocation (amount, credit_type of monetary or units, rollover_enabled and an optional rollover_max_periods) and a timing (recurrence of recurring or one_off, with an interval of monthly, quarterly, semi_annual or yearly). Alguna does not meter your application’s usage against an entitlement. Your application asks what the customer is entitled to and enforces it. To bill or limit by consumption, send usage events and use a credit-allocation entitlement when the customer should draw down an included balance.

Defining entitlements

Entitlements travel with the offer, so they are set where the offer is defined:

On a plan — the entitlements array on Create a plan, or when building the plan in the dashboard. Every subscription created from the plan inherits them.
On a subscription version — the entitlements array on Create a new subscription version or Replace a draft subscription version (the full set for that version), or the subscription editor in the dashboard. Use this to grant one customer something their plan does not.

Each entry is an entitlement_key, type, mode and (for scalar types) value:

"entitlements": [
  { "entitlement_key": "sso", "type": "boolean", "mode": "static", "value": "true" },
  { "entitlement_key": "seats", "type": "number", "mode": "static", "value": "25" },
  {
    "entitlement_key": "included_credits",
    "type": "credit_allocation",
    "mode": "grant_based",
    "allocation": { "amount": "500.00", "credit_type": "monetary", "rollover_enabled": false },
    "timing": { "recurrence": "recurring", "interval": "monthly" }
  }
]

Entitlements take effect when the version is published. Until then they belong to a draft.

Reusable entitlement configs, templates, and the transition policies that decide what happens to active grants when a version changes are managed in the dashboard under Entitlements. The public API sets entitlement values on plans and versions and reads them back; it does not manage configs or policies.

Reading entitlements

Three endpoints answer “what can this customer do?”.

One entitlement on a subscription

Get a specific entitlement — GET /subscriptions/{id}/entitlements/{key}

curl https://api.alguna.io/subscriptions/sub_abc123/entitlements/api_access \
  -H "Authorization: Bearer $ALGUNA_API_KEY" \
  -H "Alguna-Version: 2026-04-01"

import os

import requests

HEADERS = {
    "Authorization": f"Bearer {os.environ['ALGUNA_API_KEY']}",
    "Alguna-Version": "2026-04-01",
}

response = requests.get(
    "https://api.alguna.io/subscriptions/sub_abc123/entitlements/api_access",
    headers=HEADERS,
    timeout=10,
)
if response.status_code == 404:
    print("no such entitlement")
else:
    response.raise_for_status()
    print(response.json()["value"])

Response

{
  "key": "api_access",
  "mode": "static",
  "type": "boolean",
  "value": "true",
  "subscription_id": "sub_abc123",
  "version_id": "subv_abc123"
}

All entitlements on a subscription

List active entitlements — GET /subscriptions/{id}/entitlements returns every entitlement on the subscription’s current published version, static and grant-based.

curl https://api.alguna.io/subscriptions/sub_abc123/entitlements \
  -H "Authorization: Bearer $ALGUNA_API_KEY" \
  -H "Alguna-Version: 2026-04-01"

import os

import requests

HEADERS = {
    "Authorization": f"Bearer {os.environ['ALGUNA_API_KEY']}",
    "Alguna-Version": "2026-04-01",
}

response = requests.get(
    "https://api.alguna.io/subscriptions/sub_abc123/entitlements",
    headers=HEADERS,
    timeout=10,
)
response.raise_for_status()
entitlements = {e["key"]: e for e in response.json()["data"]}
print(entitlements.keys())

All entitlements for a customer

List active entitlements for a customer — GET /customers/{id}/entitlements flattens the entitlements across all of the customer’s active subscriptions. Each entry carries the subscription_id it came from. The {id} accepts the Alguna customer ID, one of the customer’s aliases, or a connected-account external ID such as a Stripe customer ID, so you can call it with the identifier you already hold.

curl https://api.alguna.io/customers/cust_abc123/entitlements \
  -H "Authorization: Bearer $ALGUNA_API_KEY" \
  -H "Alguna-Version: 2026-04-01"

import os

import requests

HEADERS = {
    "Authorization": f"Bearer {os.environ['ALGUNA_API_KEY']}",
    "Alguna-Version": "2026-04-01",
}

response = requests.get(
    "https://api.alguna.io/customers/cust_abc123/entitlements",
    headers=HEADERS,
    timeout=10,
)
response.raise_for_status()
for entitlement in response.json()["data"]:
    print(entitlement["key"], entitlement["type"], entitlement["value"], entitlement["subscription_id"])

value is always returned as a string, whatever the entitlement’s type. Parse it according to type. An entry with a null subscription_id and version_id comes from your organization’s default entitlement profile rather than from a subscription.

Checking access in your application

const BASE = "https://api.alguna.io";
const headers = {
  Authorization: `Bearer ${process.env.ALGUNA_API_KEY}`,
  "Alguna-Version": "2026-04-01",
};

// Feature flag
async function hasFeature(subscriptionId, key) {
  const res = await fetch(`${BASE}/subscriptions/${subscriptionId}/entitlements/${key}`, { headers });
  if (res.status === 404) return false;
  const entitlement = await res.json();
  return entitlement.value === "true";
}

// Numeric quota
async function getLimit(subscriptionId, key) {
  const res = await fetch(`${BASE}/subscriptions/${subscriptionId}/entitlements/${key}`, { headers });
  if (res.status === 404) return 0;
  const entitlement = await res.json();
  return Number(entitlement.value);
}

Cache the result for the length of a session rather than calling on every request. Entitlements change only when a subscription version is published, and a subscription.version.updated webhook fires when that happens, so you can invalidate on the event.

Credit allocations

For a credit_allocation entitlement, the entitlement tells you what was allocated; the balance and the draw-down live in the credits API. Check the remaining balance before allowing consumption with GET /subscriptions/{id}/credits/balance:

curl https://api.alguna.io/subscriptions/sub_abc123/credits/balance \
  -H "Authorization: Bearer $ALGUNA_API_KEY" \
  -H "Alguna-Version: 2026-04-01"

import os

import requests

HEADERS = {
    "Authorization": f"Bearer {os.environ['ALGUNA_API_KEY']}",
    "Alguna-Version": "2026-04-01",
}

response = requests.get(
    "https://api.alguna.io/subscriptions/sub_abc123/credits/balance",
    headers=HEADERS,
    timeout=10,
)
response.raise_for_status()
print(response.json())

To reserve credit before doing expensive work and settle it afterwards, use the realtime gate described in Credit Consumption.

Version changes

When a subscription moves to a new version, its transition policy decides what happens to grant-based entitlements that are being replaced:

Setting	Options
Active grants	`void` the remaining grant, or `leave_intact` until it expires
Rollover	`continue` the existing rollover, `rebalance` it against the new allocation, or `void` it

Transition policies are configured per version change in the dashboard and previewed before the change is published. See Versioning and Amendments.

Best practices

Use stable keys

Your application reads entitlements by key. Keep keys identical across plans so an upgrade never needs a code change.

Meter separately

Entitlements describe access. Bill consumption with metrics and credits.

Cache reads

Entitlements only change when a version is published; invalidate on subscription.version.updated.

Fail closed

Treat a missing entitlement (404) as no access, not unlimited access.

Next steps

Plans

Define entitlements once on the offer.

Subscription Versioning

Entitlements are read from the current published version.

Credits & Wallets

Meter and draw down credit allocations.

Webhooks

Invalidate caches when versions change.

Overview

Guides

Getting Started

Customers

Pricing & Packaging

Quotes (CPQ)

Subscriptions

Entitlements

Invoices

Credits & Wallets

Usage Metering

Approval Workflows

Automations

Collections

Tax Management

Hosted Pages

Revenue & Accounting

Multi-Currency

Data & Exports

AI

Entitlements Overview

What an entitlement is

Defining entitlements

Reading entitlements

One entitlement on a subscription

All entitlements on a subscription

All entitlements for a customer

Checking access in your application

Credit allocations

Version changes

Best practices

Use stable keys

Meter separately

Cache reads

Fail closed

Next steps

Plans

Subscription Versioning

Credits & Wallets

Webhooks

​What an entitlement is

​Defining entitlements

​Reading entitlements

​One entitlement on a subscription

​All entitlements on a subscription

​All entitlements for a customer

​Checking access in your application

​Credit allocations

​Version changes

​Best practices

Use stable keys

Meter separately

Cache reads

Fail closed

​Next steps

Plans

Subscription Versioning

Credits & Wallets

Webhooks

What an entitlement is

Defining entitlements

Reading entitlements

One entitlement on a subscription

All entitlements on a subscription

All entitlements for a customer

Checking access in your application

Credit allocations

Version changes

Best practices

Next steps