Create

Create an entitlement for a customer. This temporarily reserves funds in the customer’s wallet to guarantee payment for future usage.

POST /v0/entitlements

Create

cURL

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
}
'

201

{
  "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.

Pattern: ^cus_[a-zA-Z0-9]+$

entitlementData · object[] · required

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

Show child attributes

merchantId · string · required

ID of the merchant creating the entitlement.

Pattern: ^org_[a-zA-Z0-9]+$

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

201

application/json

Entitlement created successfully

id · string

Unique identifier for the entitlement.

Pattern: ^ent_[a-zA-Z0-9]+$

object · enum<string> · default: entitlement

Available options: entitlement

billableMetrics · object[]

Billable metrics and quantities reserved stored as JSON.

Show child attributes

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.

Pattern: ^cus_[a-zA-Z0-9]+$

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.

Pattern: ^org_[a-zA-Z0-9]+$

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

Pattern: ^[0-9]+$

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