Entitlements Overview

Manage feature access and subscription entitlements

Entitlements define what features, resources, or capabilities a customer has access to based on their subscription. Use them to control feature access, set quotas, and provision recurring credit allocations.

---

What Are Entitlements?

An entitlement is an access right attached to a subscription version:

• Feature flags — turn a capability on or off
• Quotas — a numeric limit such as seats or included storage
• Access tiers — a named level such as standard or priority
• Credit allocations — a recurring balance the customer draws down

Entitlements are configured in the dashboard and read back through the API. Your application asks Alguna what a customer is entitled to; Alguna does not meter your application’s usage against the entitlement. To bill or limit by consumption, send usage events against a billable metric, and use a credit-allocation entitlement when the customer should draw down an included balance.

---

Key Concepts

Entitlement

A key, a type and a value, attached to a subscription version.

Entitlement config

The reusable definition of an entitlement: its key, type, mode and default value.

Template

A named config you apply when building subscriptions, so plans stay consistent.

Transition policy

What happens to active grants and rollover when a subscription moves to a new version.

Type

Type	Value	Use it for
boolean	true / false	Feature flags
number	An integer	Seats, quotas, included units
string	Free text	Access tiers, plan labels
credit_allocation	A credit amount and schedule	Included balances the customer draws down

Mode

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 allocations.

A credit_allocation entitlement also carries an allocation (amount, credit type monetary or units, and whether unused balance rolls over) and a timing config (recurring or one_off, at a monthly, quarterly, semi_annual or yearly interval).

---

Creating Entitlements

Entitlements are defined in the dashboard, then attached to subscription versions.

1. Create the config

   Go to Entitlements and click New entitlement. Give it a name, a key your application will use, a type and a mode. For a credit allocation, set the amount, credit type, rollover behaviour and interval.

2. Attach it to a subscription version

   When you build or amend a subscription version, add the entitlement and set its value for that customer. See Subscription Versioning.

3. Publish the version

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

Entitlement configs, templates and transition policies are managed in the dashboard. The public API exposes entitlements read-only, as described below.

---

Reading Entitlements

Use these endpoints to decide what a customer can do in your product.

One entitlement

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

Response

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

All entitlements on a subscription

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

All entitlements for a customer

Aggregates across the customer’s active subscriptions.

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

value is always returned as a string, whatever the entitlement’s type. Parse it according to type.

---

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.

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:

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

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 entitlements that are being replaced:

Setting	Options
Active grants	Void the remaining grant, or leave it 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 Subscription Versioning and Amendments.

---

Best Practices

Use stable keys

Your application reads entitlements by key. Keep keys stable across plans.

Meter separately

Entitlements describe access. Bill consumption with metrics and credits.

Cache reads

Entitlements only change when a version is published.

Fail closed

Treat a missing entitlement as no access, not unlimited access.

---

Next Steps

Subscription Versioning

Entitlements are defined on subscription versions.

Credits & Wallets

Meter and draw down credit allocations.