Entitlements are pre-authorized payment reservations that guarantee funds availability before usage occurs. They enable real-time billing with guaranteed payment collection, eliminating unpaid usage and providing instant authorization for usage-based services.

​
What Happens When You Create an Entitlement?

  1. Reserve Funds
    Paygentic calculates the cost using the requested billableMetricId and quantity.
  2. Lock In Payment
    Funds are reserved upfront — no risk of missed payments later.
  3. Get a Token
    An entitlementId (format: com_*) is returned, which you’ll use when recording usage.
  4. Track Usage
    Each usage event references this entitlementId to deduct funds.

​
Types of Entitlements

​
Standard Entitlements (Single-Use)

Perfect for regular, everyday usage patterns. These entitlements can only be used once (maxUses = 1). 
POST /v0/entitlements
Authorization: Bearer <api-key>
Content-Type: application/json

{
  "merchantId": "org_abc123",
  "customerId": "cus_def456",
  "entitlementData": [
    {
      "billableMetricId": "bmt_api_calls",
      "quantity": 100
    }
  ]
}
Good for:
  • Standard API billing
  • Lower-volume apps
  • Single-region use cases

​
Regional (Edge-Optimized) Entitlements

Designed for speed-critical, high-volume apps — backed by Paygentic’s edge network. 
POST https://edge-api.paygentic.com/v0/entitlements
Authorization: Bearer <api-key>
Content-Type: application/json

{
  "merchantId": "org_abc123",
  "customerId": "cus_def456",
  "entitlementData": [
    {
      "billableMetricId": "bmt_tokens",
      "quantity": 10000
    }
  ],
  "maxUses": 100
}
⚠️ Important: Funds are only guaranteed up to the maxUses limit. If an entitlement is used more times than specified, fund availability is not guaranteed for the excess usage. Best for:
  • AI/ML workloads
  • Realtime analytics
  • Global apps with low-latency needs
  • High-frequency or bursty traffic

​
Routing Options

Auto Edge Routing
Let Paygentic pick the best location for you: 
curl https://edge-api.paygentic.com/v0/entitlements
Specify a Region
Hardcode the region for max consistency: 
curl https://europe-west1-edge-api.paygentic.com/v0/entitlements
Prefer a Region via Header 
curl -H "X-Paygentic-Region: asia-south1" https://api.paygentic.com/v0/entitlements
Paygentic’s edge network currently supports the following regions:
  • asia-south1 (Mumbai)
  • europe-west1 (Belgium)
  • us-west1 (Oregon) – Main region
Next, learn how to report usage and trigger billing with Usage Events.