Skip to main content
POST
/
v0
/
entitlements
Create
curl --request POST \
  --url https://api.paygentic.io/v0/entitlements \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "customerId": "<string>",
  "entitlementData": [
    {
      "billableMetricId": "<string>",
      "quantity": 1,
      "price": "<string>"
    }
  ],
  "merchantId": "<string>",
  "maxUses": 500
}
'
{
  "id": "ent_a7b8c9d0e1f2g3h4",
  "object": "entitlement",
  "billableMetrics": [
    {
      "billableMetricId": "bm_y1z2a3b4c5d6e7f8",
      "price": "0.000025",
      "quantity": 10000
    }
  ],
  "createdAt": "2024-01-20T10:00:00Z",
  "customerId": "cus_q3r4s5t6u7v8w9x0",
  "expiresAt": "2024-12-31T23:59:59Z",
  "maxUses": 1,
  "merchantId": "org_i5j6k7l8m9n0o1p2",
  "region": "global",
  "remainingBalance": "100000000000",
  "usedCount": 0
}

Authorizations

​
Authorization
string
header
required

API key authentication

Body

application/json
​
customerId
string
required

ID of the customer to create the entitlement for.

​
entitlementData
object[]
required

Array of consumption metrics with quantities to pre-authorize payment for.

​
merchantId
string
required

ID of the merchant creating the entitlement.

​
maxUses
integer

Maximum consumption events allowed before expiration (optional). Defaults to 1 for global entitlements, 100 for regional entitlements.

Required range: 1 <= x <= 1000

Response

Entitlement created successfully

​
id
string

Unique identifier for the entitlement.

​
object
enum<string>
default:entitlement
Available options:
entitlement
​
billableMetrics
object[]

Billable metrics and quantities reserved stored as JSON.

​
createdAt
string<date-time>

Entitlement creation timestamp in ISO 8601 format. Sample values: '2024-01-15T10:30:00Z', '2024-02-01T14:45:30Z'

​
customerId
string

ID of the customer this entitlement is for.

​
expiresAt
string<date-time>

Entitlement expiration timestamp in ISO 8601 format. Sample values: '2024-12-31T23:59:59Z', '2025-01-15T10:30:00Z'

​
maxUses
integer

Maximum consumption events allowed before entitlement expires. Sample values: 1 allows single use, 10 allows ten uses, 100 allows one hundred uses

Required range: x >= 1
​
merchantId
string

ID of the merchant that created this entitlement.

​
region
string

Geographic restriction zone limiting where this entitlement applies. Sample values: 'us-west-2' confines usage to AWS US West 2 region, 'eu-central-1' confines usage to EU Central 1 region, 'global' permits usage from all regions

​
remainingBalance
string

Unused entitlement balance in atomic units (string representation of BigInt). Sample values: '100000000000' equals $100.00 remaining, '50000000000' equals $50.00 remaining, '0' equals fully consumed

​
usedCount
integer

Count of consumption events processed using this entitlement. Sample values: 0 indicates unused, 5 indicates five events processed, 10 indicates ten events processed

Required range: x >= 0