> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tirdad.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Entitlement Grants

> Configure time-boxed usage quotas on entitlements: rolling windows, parallel limits, and amount-based caps with exhaustion alerts and overage billing

An [entitlement](https://docs.tirdad.ai/docs/product-catalogue/features/linking-to-plans.md) resets once a billing period. Entitlement grants let it reset on a shorter clock instead, so you can offer 1M tokens every 5 hours or \$50 of compute a day. Tirdad opens a window when usage starts, tracks consumption against the quota, fires a webhook when the quota is exhausted, and bills anything beyond it as overage.

**Benefits:**

* **Rolling limits:** quotas measured in hours, days, or weeks instead of the billing period
* **Parallel limits:** stack independent windows on one feature, such as an hourly limit and a weekly limit
* **Amount-based quotas:** cap spend in currency, priced through your existing billing pipeline
* **Exhaustion webhooks:** `entitlement.grant.exhausted` fires when a window's quota is used up
* **Overage billing:** usage beyond the quota lands on the arrears invoice automatically

## Concepts

| Term | Meaning |
| - | - |
| **Allowance** | The rule you configure on an entitlement: how much, how often, and how it stacks. |
| **Window** | One concrete stretch of time instantiated from that rule, with its own quota and its own usage. A grant that resets hourly produces one window per hour of activity. |
| **Value type** | What the quota counts: quantity (meter units) or amount (currency, priced through your existing meter prices). |
| **Stacking** | How several allowances on the same feature combine: additive merges them into one pool, parallel keeps each on its own clock. |

## Steps to set up a grant

Entitlements are supported at the plan and addon level, with the same fields on both. The steps below configure a plan's entitlement.

**1. Open the plan's entitlements**

Go to **Product Catalog** and open the plan, then the **Entitlements** section. Click **Add**.

![Add an entitlement to a plan](https://mintcdn.com/tirdad/Ca7Kginb789boSAj/images/docs/product-catalogue/features/entitlement-grants/select-feature.png?fit=max\&auto=format\&n=Ca7Kginb789boSAj\&q=85\&s=826001bc5d92e93d0711e1adfb67aa86)

**2. Pick the feature and set the value**

Select the metered feature you want to grant a recurring value for. The value fields appear once it is chosen.

**Value Type**

* **Quantity** counts meter units, such as tokens or images.
* **Amount** caps spend in currency, priced through the meter's existing prices.

**Value**

* The amount granted in each window.

> [!NOTE]
>
> Switch on **Unlimited** to grant a value with no ceiling. Usage is still tracked and shown, but nothing is ever exhausted and no overage is billed.

![Configure an entitlement grant](https://mintcdn.com/tirdad/Ca7Kginb789boSAj/images/docs/product-catalogue/features/entitlement-grants/add-entitlement.png?fit=max\&auto=format\&n=Ca7Kginb789boSAj\&q=85\&s=1828e0f103c49265aa190394383b06e3)

**3. Choose how often it resets**

**Usage resets** sets the cadence: **Hourly**, **Daily**, **Weekly**, or **Every billing period**. This is what makes the allowance recurring rather than a single limit for the cycle.

**4. Set the advanced options if you need them**

Under **Advanced**, **Window starts** decides where each window begins and **Stacking** decides how this value combines with others on the same feature. See [Where a Window Starts](#where-a-window-starts) and [Stacking](#stacking).

**5. Save**

Click **Add**, then save the plan. The value applies to every customer on the plan, now and on every later subscription.

### API Fields

Every setting above is a field on the [create entitlement](https://docs.tirdad.ai/api-reference/entitlements/create-entitlement.md) and [update entitlement](https://docs.tirdad.ai/api-reference/entitlements/update-entitlement.md) endpoints.

| Dashboard | API field | Values |
| - | - | - |
| Value Type | `grant_measure` | `quantity` or `amount` |
| Value | `grant_quota` | A decimal string |
| Unlimited | `grant_unlimited` | `true` for no ceiling. Mutually exclusive with `grant_quota`. |
| Usage resets | `grant_duration_unit` and `grant_duration_value` | `hour`, `day`, `week`, or `subscription_period` |
| Window starts | `grant_allocation_behavior` | `first_usage` or `unit_start` |
| Stacking | `aggregation_mode` | `additive` or `parallel` |

### Validation Rules

An allowance is checked when you save it, and refused if it breaks any of these.

| Rule | Detail |
| - | - |
| The feature must be metered | Meters using `MAX` aggregation or bucketed aggregation are not supported |
| One value type and one stacking per feature | Every allowance on the same feature must agree. Additive allowances must share the same cadence as well. |
| Amount allowances need flat pricing | The meter must price per unit at a flat rate. Tiered prices are refused. |
| Unlimited needs a cycle-length cadence | Available only with **Every billing period**. A recurring window needs a finite value. |
| A window must last at least an hour | Applies to the hourly, daily and weekly cadences |

### Unlimited Allowances

Switch on **Unlimited** to give a customer an uncapped allowance for the billing cycle. The entitlement still reports usage and still appears in the ledger, but no quota is enforced, nothing is ever exhausted, and no overage is billed.

This is how you remove a ceiling from a metered entitlement. Use it in place of the legacy `usage_limit` and `usage_reset_period` fields, which metered entitlements are moving off.

### Where a Window Starts

**Window starts** decides how each new window is anchored:

* **On first use** (`first_usage`) starts the window at the customer's first event past the covered range. An event at 2:07 opens a window that runs 2:07 to 7:07 for a five-hour allowance, so each customer's windows follow their own activity.
* **Calendar boundary** (`unit_start`) rounds the start down to the hour, day or week. That same event at 2:07 opens a window running 2:00 to 7:00. Use it when every customer should see the allowance reset on the clock.

The setting applies only to fixed cadences. An allowance that resets every billing period always runs with the subscription cycle.

### Changing an Allowance Mid-Cycle

Editing an entitlement that customers are already using does not always take effect at once, because a window that is open has usage measured against it already.

| Change | When it takes effect |
| - | - |
| Raising the value | Immediately, on the open window |
| Lowering the value, still above what has been used | Immediately, on the open window |
| Lowering the value below what has been used | Immediately: the open window has nothing left, so further usage bills as overage |
| Changing the cadence, value type or stacking | When the current window ends |

Usage already recorded in the open window still counts. A customer on a 1,000 unit hourly allowance who has spent 400 and is moved to 600 has 200 left, not 600. Moved to 300 instead, they have nothing left, and every unit they use for the rest of the window bills as overage. These timings are for additive stacking, the default. For a cadence, value type or stacking change, the dashboard shows when the new rule starts before you save.

> [!WARNING]
>
> This applies to an entitlement edited on a **subscription**. Editing the **plan's** entitlement changes the rule for future windows and for new subscribers; it does not re-cut windows already open on existing subscriptions.

## How Grant Windows Work

Windows are usage-anchored. Tirdad does not open a window on a fixed schedule; it opens one when usage arrives:

1. The first usage event past the covered range opens a window, anchored according to **Window starts**.
2. The window runs for the configured cadence.
3. When the window ends, nothing happens until the next usage event. Idle periods open no windows, so an inactive customer accumulates nothing.
4. Windows never straddle billing cycles. A window that would end within an hour of the cycle boundary stretches to the boundary instead of leaving a short stub.

A window is **active** while usage is below its quota and **exhausted** once usage reaches it. Expiry is not a state: a window is closed when its end has passed, regardless of how much was used.

> [!NOTE]
>
> Usage is measured against the window's own time range, not accumulated as events arrive. An event that reaches Tirdad late counts against the window its timestamp falls in, so a backfill can change what a window that has already closed reports, and can exhaust it after the fact.

## Viewing Usage and Windows

A customer's **Entitlements** table lists what they hold and how much of it they have spent.

![Entitlements on a customer, with values, stacking and usage](https://mintcdn.com/tirdad/Ca7Kginb789boSAj/images/docs/product-catalogue/features/entitlement-grants/entitlements-table.png?fit=max\&auto=format\&n=Ca7Kginb789boSAj\&q=85\&s=d065c6fb02d1becdf6f043fd5d6ad944)

| Column | Shows |
| - | - |
| Feature | The metered feature the allowance is on |
| Source | Where the allowance comes from: the plan, an addon, or the subscription itself when it was edited there |
| Value | The allowance and its cadence, such as `100,000 / hour` or `50 / billing period`, or `Unlimited` |
| Mode | `Additive` or `Parallel` |
| Measure | `Quantity` or `Amount` |
| Usage | Consumption against the live allowance |

A parallel feature gets one row per budget, since no single pair of numbers describes them together. In the example above, Image Generations carries 500 per day from the Pro plan and 5,000 per week from the Token Booster addon, each metering the same usage on its own clock.

Selecting a row opens **Grants**, the ledger of windows behind that number.

![The grants ledger for a feature, one row per window](https://mintcdn.com/tirdad/Ca7Kginb789boSAj/images/docs/product-catalogue/features/entitlement-grants/grants-ledger.png?fit=max\&auto=format\&n=Ca7Kginb789boSAj\&q=85\&s=ee2f2c1c63578a973fa47822f54af8c7)

| Status | Meaning |
| - | - |
| Active | Open now, with quota left |
| Exhausted | The value was fully used before the window ended (hover the status to see when it was crossed) |
| Closed | The window ended without the quota being reached |

### Reading Windows Over the API

[Get customer usage summary](https://docs.tirdad.ai/api-reference/customers/get-customer-usage-summary.md) returns the grant config for each feature plus a `grant_state.allowances` array, one entry per window:

| Field | Description |
| - | - |
| `quota`, `usage` | The window's ceiling and what has been spent against it |
| `remaining` | What is left. Absent on an unlimited window, where there is no ceiling to measure against. |
| `valid_from`, `valid_to` | The window boundaries |
| `status` | `active` or `exhausted` |
| `is_active` | Whether the window is open right now, decided by the server's clock rather than the caller's. |
| `quota_crossed_at` | When a usage evaluation first found the window at or over its quota. This is the evaluation time, not the time of the usage event that crossed the quota, so it can trail the real crossing. Absent while the window still has room, and on an unlimited window. It only affects billing when windows overlap, as with parallel allowances on one feature: overage is then billed from this timestamp to `valid_to`, so usage between the real crossing and this timestamp is not billed as overage. Windows that do not overlap bill everything above the quota, whenever it arrived: a quota of 100 with 150 used bills 50. |
| `unlimited` | `true` when the window has no ceiling |

Only the current billing period is returned, capped at the three most recent windows per entitlement.

A **parallel** feature also carries a `buckets` array, one entry per budget with its own quota, cadence and value type. Read those instead of `total_limit` when `buckets` is present.

Allowances are listed per subscription rather than merged, so a customer holding one feature on two subscriptions sees two sets of windows. Tell them apart with `entitlement_id`. Inherited subscriptions carry none of their own; their usage belongs to the [parent](https://docs.tirdad.ai/docs/subscriptions/customer-hierarchy.md).

## Stacking

When a customer holds more than one allowance on the same feature, such as a plan entitlement plus an addon entitlement, **Stacking** decides how they combine.

### Additive

All allowances merge into **one** window whose quota is their sum. Use this when an addon should top up the base allowance.

**Example**: The Pro plan grants 100K tokens per day. A booster addon grants another 50K per day. The customer gets one daily window with a 150K quota.

### Parallel

Each allowance opens its **own** window on its own clock. All of them meter the same usage stream. A request is within limits only while every applicable window has quota left; exhausting any one window puts the feature into overage for the remainder of that window.

**Example**: 1M tokens per 5 hours *and* 5M tokens per week, as two parallel allowances. Heavy use exhausts the 5-hour window first; sustained use over days exhausts the weekly window even though no single 5-hour burst did.

## Use Cases

### Rolling Rate Limits for an AI Product

Cap token consumption in a rolling window that has nothing to do with the monthly invoice, the pattern used by AI assistants that advertise "resets every 5 hours".

| Setting | Value |
| - | - |
| Value Type | Quantity |
| Value | 1,000,000 |
| Usage resets | Every 5 hours |
| Window starts | Calendar boundary |
| Stacking | Parallel |

Create this allowance through the API with `grant_duration_unit: "hour"` and `grant_duration_value: 5`. The dashboard's **Hourly** option always creates a one-hour window, so it cannot set up a five-hour one.

Add a second parallel allowance that resets weekly to layer a sustained ceiling on top of the burst limit.

### Daily Spend Cap

Cap what a customer's usage *costs* rather than how many units they consume. An amount allowance prices usage through your existing meter prices, so a mid-window price change is respected.

| Setting | Value |
| - | - |
| Value Type | Amount |
| Value | 50 |
| Usage resets | Daily |
| Stacking | Additive |

The customer gets \$50 of compute per day. Alert on exhaustion, or let usage continue and bill the excess as overage.

### Plan Plus Booster Addon

Sell top-ups without new plumbing. The plan carries an allowance; the addon carries another on the same feature with **Additive** stacking. Buying the addon raises the shared window's quota by the addon's amount. With **Parallel** instead, the addon grants a separate window, useful when its allowance runs on its own clock.

### Soft Limits With Billed Overage

Grants implement soft limits: usage is never blocked. When a window's quota is crossed, usage recorded after the crossing is billed as overage on the subscription's arrears invoice. Quantity overage is priced as billable units; amount overage lands directly as a charge. With parallel windows, overlapping overage periods are merged so a unit of usage is never billed twice.

> [!NOTE]
>
> Overage folding skips line items with tiered prices, commitments, or true-up. Those price against the full cycle, so grant overage on them falls back to the standard billing calculation.

## Exhaustion Alerts

Usage is measured shortly after events arrive, within roughly five minutes. When a window's usage reaches its quota the window turns exhausted and a webhook fires, once per window. There is no recovery event: a fresh window with a fresh quota simply opens when the next one starts.

### Webhook Payload

**Event type:** `entitlement.grant.exhausted`

```json theme={null}
{
  "event_type": "entitlement.grant.exhausted",
  "alert_type": "entitlement_grant_exhausted",
  "alert_status": "in_alarm",
  "usage_ratio": "1.15",
  "triggered_at": "2026-07-25T20:20:23Z",
  "subscription": {
    "id": "subs_01KYARKSC3GVX64QEF4T4ABS9X",
    "customer_id": "cust_01KYARB3TVZ0RZPDGC5P40NHHC",
    "plan_id": "plan_pro",
    "subscription_status": "active",
    "currency": "usd",
    "billing_period": "MONTHLY",
    "current_period_start": "2026-07-24T19:11:06Z",
    "current_period_end": "2026-08-24T19:11:06Z"
  },
  "customer": {
    "id": "cust_01KYARB3TVZ0RZPDGC5P40NHHC",
    "external_id": "cust-new",
    "name": "Acme Corp",
    "email": "billing@acme.com"
  },
  "entitlement": {
    "id": "ent_01KYB5ESPNNB8DWFVQAFJN6KKZ",
    "feature_id": "feat_tokens",
    "feature_type": "metered",
    "grant_measure": "quantity",
    "grant_quota": "1000000",
    "grant_duration_value": 5,
    "grant_duration_unit": "hour",
    "aggregation_mode": "parallel"
  },
  "entitlement_grant": {
    "id": "eg_01KYDEZ86JA78AM7F7Y2SMTRWE",
    "entitlement_config_id": "ent_01KYB5ESPNNB8DWFVQAFJN6KKZ",
    "customer_id": "cust_01KYARB3TVZ0RZPDGC5P40NHHC",
    "subscription_id": "subs_01KYARKSC3GVX64QEF4T4ABS9X",
    "scope_entity_type": "feature",
    "scope_entity_id": "feat_tokens",
    "measure": "quantity",
    "quota": "1000000",
    "usage": "1150000",
    "valid_from": "2026-07-25T15:20:00Z",
    "valid_to": "2026-07-25T20:20:00Z",
    "grant_status": "exhausted",
    "quota_crossed_at": "2026-07-25T20:20:23Z"
  }
}
```

### Webhook Fields

| Field | Description |
| - | - |
| `alert_type` | Always `entitlement_grant_exhausted` |
| `alert_status` | `in_alarm` when the quota is exhausted |
| `usage_ratio` | `usage / quota` at evaluation time, `1` or more when exhausted |
| `triggered_at` | When the exhaustion was detected |
| `subscription` | The owning subscription, without line items or plan expansions |
| `customer` | The customer the grant belongs to |
| `entitlement` | The allowance the window was instantiated from |
| `entitlement_grant` | The exhausted window, including `quota`, `usage`, and the window boundaries |

> [card] [Link features to plans](https://docs.tirdad.ai/docs/product-catalogue/features/linking-to-plans.md)
>
> Attach a feature to a plan or addon as an entitlement.

> [card] [Webhooks](https://docs.tirdad.ai/developers/webhooks/event-catalog.md#feature-and-entitlement-events)
>
> Subscribe to `entitlement.grant.exhausted` and the rest of the event catalogue.

**API References**

* [Create an Entitlement](https://docs.tirdad.ai/api-reference/entitlements/create-entitlement.md)
* [Update an Entitlement](https://docs.tirdad.ai/api-reference/entitlements/update-entitlement.md)
* [Get Customer Usage Summary](https://docs.tirdad.ai/api-reference/customers/get-customer-usage-summary.md)
* [Get Customer Entitlements](https://docs.tirdad.ai/api-reference/customers/get-customer-entitlements.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.