POST
/
entitlements
Create an entitlement
curl --request POST \
  --url https://api.paygentic.io/v0/entitlements \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "merchantId": "<string>",
  "customerId": "<string>",
  "entitlementData": [
    {
      "billableMetricId": "<string>",
      "quantity": 1,
      "price": "<string>"
    }
  ],
  "maxUses": 500
}'
{
  "id": "<string>",
  "object": "entitlement",
  "merchantId": "<string>",
  "customerId": "<string>",
  "billableMetrics": [
    {
      "billableMetricId": "<string>",
      "quantity": 123,
      "price": "<string>"
    }
  ],
  "expiresAt": "2023-11-07T05:31:56Z",
  "createdAt": "2023-11-07T05:31:56Z",
  "region": "<string>",
  "maxUses": 2,
  "remainingBalance": "<string>",
  "usedCount": 1
}

Authorizations

​
Authorization
string
header
required

API key authentication

Body

application/json
​
merchantId
string
required

ID of the merchant creating the entitlement.

​
customerId
string
required

ID of the customer to create the entitlement for.

​
entitlementData
object[]
required

Array of billable metrics and quantities to reserve.

​
maxUses
integer

Maximum number of times this entitlement can be used (optional, defaults to 1 for global, 100 for regional).

Required range: 1 <= x <= 1000

Response

Entitlement created successfully

​
id
string

Unique identifier for the entitlement.

​
object
enum<string>
default:entitlement
Available options:
entitlement
​
merchantId
string

ID of the merchant that created this entitlement.

​
customerId
string

ID of the customer this entitlement is for.

​
billableMetrics
object[]

Billable metrics and quantities reserved stored as JSON.

​
expiresAt
string<date-time>

Expiration time for the entitlement.

​
createdAt
string<date-time>

Timestamp when the entitlement was created.

​
region
string

Region where this entitlement is constrained (e.g., 'us-west-2', 'global').

​
maxUses
integer

Maximum number of times this entitlement can be used.

Required range: x >= 1
​
remainingBalance
string

Remaining balance for this entitlement in nanodollars (string representation of BigInt).

​
usedCount
integer

Number of times this entitlement has been used.

Required range: x >= 0