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

# Entitlements

> Pre-authorized payment reservations for guaranteed billing

Entitlements solve the fundamental problem of payment certainty in consumption-based billing. By reserving funds before usage occurs, they eliminate payment risk while enabling instant authorization for metered services.

<Info>
  This page describes Legacy Billing entitlements — pre-authorized payment reservations
  denominated in currency. For Standard Billing, see
  [Metered Entitlements](/platform/billing/metered-entitlements) for unit-denominated grants, or
  [Billing Versions](/platform/billing/billing-versions) for a full comparison of the two models.
</Info>

## Core mechanism

An entitlement is a cryptographically-secured commitment that bridges the gap between customer intent and merchant fulfillment. When created, the system:

1. Calculates total cost based on requested metrics and quantities
2. Reserves funds from the customer's payment instrument
3. Issues a unique commitment identifier
4. Maintains a decrementable balance for consumption tracking

This pre-authorization model transforms unpredictable pay-per-use into deterministic transactions.

## Architectural models

### Single-use commitments

Traditional flow for standard workloads. One commitment per consumption event ensures strict atomicity and simplified reconciliation.

**Characteristics:**

* Immutable once consumed
* Linear processing path
* Ideal for predictable patterns
* Minimal state management overhead

### Multi-use commitments

Optimized for high-frequency operations. A single commitment supports multiple consumption events until exhaustion.

**Characteristics:**

* Configurable usage limit (maxUses parameter)
* Amortized authorization cost
* Reduced network round-trips
* Stateful balance tracking

**Critical constraint:** Fund guarantee only extends to the declared usage limit. Excess consumption beyond maxUses operates without payment assurance.

## Regional distribution

Entitlements leverage geographic distribution for latency optimization. The system maintains regional ledgers that synchronize asynchronously while preserving consistency guarantees.

### Deployment topology

**Global Instance**

* Primary source of truth
* Full transaction history
* Cross-region reconciliation
* Fallback for regional failures

**Edge Instances**

* Localized authorization
* Sub-millisecond validation
* Regional balance caching
* Eventually consistent with global

### Region selection strategies

**Automatic Routing**
Geographic proximity detection routes to nearest available region. Suitable for most applications without specific latency requirements.

**Explicit Region Binding**
Direct regional endpoint targeting for deterministic behavior. Essential for compliance or data sovereignty requirements.

**Preference Headers**
Soft regional hints allow fallback to alternatives during outages. Balances availability with performance goals.

## Consumption mechanics

Usage events reference entitlements through commitment identifiers. The processing pipeline:

1. Validates commitment existence and validity
2. Verifies sufficient remaining balance
3. Decrements commitment atomically
4. Credits merchant immediately
5. Updates distributed ledgers

This flow guarantees exactly-once semantics even under failure conditions.

## Balance management

Each entitlement maintains:

* **Initial allocation** - Original reserved amount
* **Remaining balance** - Available for future consumption
* **Usage counter** - Consumption events processed
* **Expiration timestamp** - Validity window

Balance operations are atomic and consistent within a region, with eventual consistency across regions.

## Failure modes

### Insufficient balance

Consumption attempts exceeding remaining balance fail immediately. No partial consumption occurs.

### Expired commitments

Time-bounded entitlements reject usage after expiration. Unused funds return to customer automatically.

### Regional unavailability

Automatic failover to alternate regions maintains service continuity. May introduce temporary latency increase.

### Usage limit exceeded

Multi-use commitments beyond maxUses process without fund guarantee. Merchant assumes payment risk.

## Performance characteristics

**Single-Use Commitments**

* Authorization: \~50ms (regional), \~200ms (global)
* Consumption: \~10ms (regional), \~100ms (global)
* State overhead: Minimal

**Multi-Use Commitments**

* Authorization: \~50ms (regional), \~200ms (global)
* Consumption: \~5ms (regional), \~50ms (global)
* State overhead: Linear with maxUses

## Design patterns

### Burst protection

Pre-create entitlement pools during low-traffic periods. Consume from pool during traffic spikes to maintain consistent latency.

### Geographic affinity

Pin customers to specific regions for predictable performance. Route all entitlements and consumption through designated endpoints.

### Cascading fallback

Attempt regional commitment first, fall back to global on failure. Trades latency for availability during partial outages.

### Commitment pooling

Aggregate small transactions into larger entitlements. Reduces authorization overhead for high-volume, low-value events.

## Implementation considerations

**Idempotency Requirements**
All entitlement operations must include unique identifiers. Prevents duplicate reservations during network retries.

**Expiration Strategy**
Set expiration based on expected consumption patterns. Too short risks unused funds; too long delays fund recycling.

**Regional Compliance**
Data residency laws may restrict regional deployment. Verify legal requirements before enabling edge distribution.

**Monitoring Metrics**
Track authorization latency, consumption rate, balance utilization, and regional distribution for capacity planning.

## Next steps

* [Usage Events](/platform/billing/usage-events) - Consume entitlements and trigger billing
* [Customer Lifecycle](/platform/billing/customer-lifecycle) - End-to-end billing flows
* [Accounts](/platform/payments/accounts) - Payment instrument management