Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.paygentic.io/llms.txt

Use this file to discover all available pages before exploring further.

Grants require Standard Billing (billingVersion: 1) and an active metered entitlement. See Metered Entitlements for how entitlements are provisioned automatically via subscription, and Billing Versions for details on the two billing models.
Grants let you add credits to a customer’s metered entitlement outside the normal subscription cycle. Use them for mid-cycle top-ups, promotional credits, support adjustments, or self-serve credit purchases. There are two ways to create a grant:
Direct CreatePurchase
Use casePromos, comps, support credits, backend scriptsCustomer-initiated self-serve top-ups
PaymentNone — credits are applied immediatelyCustomer pays via hosted checkout
Grant timingImmediate (or scheduled via effectiveAt)Created automatically after payment completes
EndpointPOST /v1/entitlements/{id}/grantsPOST /v1/entitlements/{id}/grants/purchase

​
Prerequisites

Before creating or purchasing a grant, you need:
  • A customer with an active v1 subscription
  • A metered entitlement on that subscription (the entitlementId)
You can retrieve the entitlement ID from GET /v1/entitlements or from the subscription’s entitlement list.

​
Creating a Grant (Direct)

Use direct creation when you want to credit a customer’s balance without requiring payment — promotional credits, support adjustments, or backend automation. 
curl -X POST "https://api.paygentic.io/v1/entitlements/ent_abc123/grants" \
  -H "Authorization: Bearer sk_test_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 500,
    "idempotencyKey": "promo-500-march-2026"
  }'
Response: 
{
  "object": "grant",
  "id": "grt_x7k9m2",
  "entitlementId": "ent_abc123",
  "amount": 500,
  "effectiveAt": "2026-03-14T10:30:00Z",
  "expiresAt": null,
  "voidedAt": null,
  "createdAt": "2026-03-14T10:30:00Z"
}

​
Request fields

FieldTypeRequiredDescription
amountnumberYesCredits to grant. Must be greater than 0.
idempotencyKeystringYesUnique key per entitlement to prevent duplicate grants. Max 255 characters.
effectiveAtdatetimeNoWhen the grant becomes effective. Defaults to the entitlement’s current period start.
expiresAtdatetimeNoWhen the grant expires. If omitted, the grant does not expire.
The idempotencyKey is scoped to the entitlement. Retrying a request with the same key returns the existing grant without creating a duplicate. If you retry with the same key but different parameters (for example, a different amount), the API returns a 409 Conflict.

​
Purchasing a Grant

Use grant purchases when a customer should pay for additional credits — self-serve top-up flows, credit packs, or on-demand capacity. The purchase endpoint creates an ad-hoc invoice with a payment session. Redirect the customer to the returned payment URL — once they complete payment, the grant is created automatically with no further action required on your end. 
curl -X POST "https://api.paygentic.io/v1/entitlements/ent_abc123/grants/purchase" \
  -H "Authorization: Bearer sk_test_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 1000,
    "price": "5.00",
    "idempotencyKey": "topup-1000-march-2026",
    "successUrl": "https://example.com/credits/success",
    "cancelUrl": "https://example.com/credits"
  }'
Response: 
{
  "object": "grant_purchase",
  "invoiceId": "inv_a1b2c3d4",
  "entitlementId": "ent_abc123",
  "grantAmount": 1000,
  "price": "5.00",
  "currency": "usd",
  "paymentSessions": [
    {
      "url": "https://platform.paygentic.io/portal/pay/ps_abc123",
      "expiresAt": "2026-03-15T10:30:00Z",
      "amount": 500
    }
  ]
}

​
Request fields

FieldTypeRequiredDescription
amountnumberYesCredits to grant upon payment completion. Must be greater than 0.
pricestringYesPrice in decimal format (e.g., "5.00"). Minimum "0.50".
idempotencyKeystringYesUnique key for deduplication. Retrying with the same key returns the existing invoice. If you retry with the same key but different parameters, the API returns a 409 Conflict. Max 255 characters.
effectiveAtdatetimeNoWhen the grant becomes effective. Defaults to the entitlement’s current period start.
expiresAtdatetimeNoWhen the grant expires. If omitted, the grant does not expire.
successUrlstringNoURL to redirect the customer to after successful payment.
cancelUrlstringNoURL to redirect the customer to if they cancel payment.
paymentExpiresAtdatetimeNoWhen the payment session expires. Uses the default expiry if omitted.
The currency is always the merchant’s default currency. The amount in the payment session is in the currency’s minor unit (e.g., cents for USD), so a price of "5.00" appears as 500.

​
What happens if payment expires

If the customer does not complete payment before the session expires, Paygentic automatically cancels the invoice. No grant is created and no charge is made.

​
Managing Grants

​
List grants

Retrieve all grants for an entitlement. Active grants are returned by default. 
curl "https://api.paygentic.io/v1/entitlements/ent_abc123/grants" \
  -H "Authorization: Bearer sk_test_YOUR_API_KEY"
Pass includeVoided=true to include voided grants in the response: 
curl "https://api.paygentic.io/v1/entitlements/ent_abc123/grants?includeVoided=true" \
  -H "Authorization: Bearer sk_test_YOUR_API_KEY"
Response: 
{
  "object": "list",
  "data": [
    {
      "object": "grant",
      "id": "grt_x7k9m2",
      "entitlementId": "ent_abc123",
      "amount": 500,
      "effectiveAt": "2026-03-14T10:30:00Z",
      "expiresAt": null,
      "voidedAt": null,
      "createdAt": "2026-03-14T10:30:00Z"
    }
  ],
  "pagination": {
    "total": 1,
    "limit": 20,
    "offset": 0
  }
}

​
Get a grant

curl "https://api.paygentic.io/v1/entitlements/ent_abc123/grants/grt_x7k9m2" \
  -H "Authorization: Bearer sk_test_YOUR_API_KEY"
Response: 
{
  "object": "grant",
  "id": "grt_x7k9m2",
  "entitlementId": "ent_abc123",
  "amount": 500,
  "effectiveAt": "2026-03-14T10:30:00Z",
  "expiresAt": null,
  "voidedAt": null,
  "createdAt": "2026-03-14T10:30:00Z"
}

​
Void a grant

Voiding removes the grant’s credits from the customer’s balance. This operation is idempotent — voiding an already-voided grant returns the grant without error. 
curl -X DELETE "https://api.paygentic.io/v1/entitlements/ent_abc123/grants/grt_x7k9m2" \
  -H "Authorization: Bearer sk_test_YOUR_API_KEY"
Response: 
{
  "object": "grant",
  "id": "grt_x7k9m2",
  "entitlementId": "ent_abc123",
  "amount": 500,
  "effectiveAt": "2026-03-14T10:30:00Z",
  "expiresAt": null,
  "voidedAt": "2026-03-15T09:00:00Z",
  "createdAt": "2026-03-14T10:30:00Z"
}

​
Grant Object

FieldTypeDescription
objectstringAlways "grant".
idstringUnique identifier (grt_ prefix).
entitlementIdstringThe entitlement this grant belongs to.
amountnumberThe number of credits granted.
effectiveAtdatetimeWhen the grant becomes effective.
expiresAtdatetime | nullWhen the grant expires. null means no expiration.
voidedAtdatetime | nullWhen the grant was voided. null means the grant is active.
createdAtdatetimeWhen the grant was created.

​
Next Steps

  • Metered Entitlements — Grant lifecycle, reset behavior, rollover rules, and balance checking
  • Features — Feature types and how entitlements are provisioned automatically
  • Usage Events — Send consumption data that depletes grant balances