Skip to main content
POST
/
v1
/
entitlements
/
{entitlementId}
/
grants
/
purchase
curl --request POST \
  --url https://api.paygentic.io/v1/entitlements/{entitlementId}/grants/purchase \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "amount": 1000,
  "price": "5.00",
  "idempotencyKey": "purchase-march-2026-topup"
}
'
{
  "object": "grant_purchase",
  "invoiceId": "<string>",
  "entitlementId": "<string>",
  "grantAmount": 123,
  "price": "<string>",
  "currency": "<string>",
  "paymentSessions": [
    {
      "url": "<string>",
      "expiresAt": "2023-11-07T05:31:56Z",
      "amount": 123
    }
  ]
}

Authorizations

​
Authorization
string
header
required

API key authentication

Path Parameters

​
entitlementId
string
required

The unique identifier of the entitlement

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

Body

application/json
​
amount
number
required

The number of credits to grant upon payment completion.

Must be a multiple of 1e-8
​
price
string
required

The price in decimal format (e.g., '5.00' for $5.00 USD). A non-negative decimal with at most 9 fractional digits (nanodollar precision). Must be at least $0.50 and must not exceed 4503599.62 (the maximum supported grant purchase amount).

Pattern: ^\d+(\.\d{1,9})?$
​
idempotencyKey
string
required

Caller-provided deduplication key. Retrying with the same key returns the existing invoice.

Required string length: 1 - 255
​
effectiveAt
string<date-time>

When the grant becomes effective. Defaults to now.

​
expiresAt
string<date-time> | null

When the grant expires. If omitted, the grant does not expire.

​
successUrl
string<uri>

URL to redirect the customer to after successful payment.

​
cancelUrl
string<uri>

URL to redirect the customer to if payment is cancelled.

​
paymentExpiresAt
string<date-time>

When the payment session expires. If omitted, uses the default expiry.

​
resetMaxRollover
number

Maximum balance carried over at the entitlement's reset boundary. If omitted, the purchased grant balance rolls over until consumed or expired. Set to 0 to discard any remaining balance at each reset. Ignored when the target entitlement has no usagePeriod (one-time entitlement) — one-time entitlements have no reset boundary, so this field has no effect.

Required range: 0 <= x <= 999999999999
​
resetMinRollover
number

Minimum balance at the entitlement's reset boundary; balances below this are floored up. Defaults to 0 (no floor). Ignored when the target entitlement has no usagePeriod (one-time entitlement).

Required range: 0 <= x <= 999999999999

Response

Grant purchase invoice created with payment session.

​
object
enum<string>
default:grant_purchase
required
Available options:
grant_purchase
​
invoiceId
string
required

The invoice ID for this grant purchase.

Pattern: ^inv_[a-f0-9]+$
​
entitlementId
string
required

The entitlement that will receive the grant.

Pattern: ^ent_[a-zA-Z0-9]+$
​
grantAmount
number
required

The number of credits that will be granted on payment.

​
price
string
required

The price in decimal format (e.g., '5.00').

​
currency
string
required

The three-letter ISO 4217 currency code (e.g., 'usd').

​
paymentSessions
object[]
required

Payment session(s) for the customer to complete the purchase.