Grants

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 Create	Purchase
Use case	Promos, comps, support credits, backend scripts	Customer-initiated self-serve top-ups
Payment	None — credits are applied immediately	Customer pays via hosted checkout
Grant timing	Immediate (or scheduled via `effectiveAt`)	Created automatically after payment completes
Endpoint	`POST /v1/entitlements/{id}/grants`	`POST /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

Field	Type	Required	Description
`amount`	number	Yes	Credits to grant. Must be greater than 0.
`idempotencyKey`	string	Yes	Unique key per entitlement to prevent duplicate grants. Max 255 characters.
`effectiveAt`	datetime	No	When the grant becomes effective. Defaults to the entitlement’s current period start.
`expiresAt`	datetime	No	When 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

Field	Type	Required	Description
`amount`	number	Yes	Credits to grant upon payment completion. Must be greater than 0.
`price`	string	Yes	Price in decimal format (e.g., `"5.00"`). Minimum `"0.50"`.
`idempotencyKey`	string	Yes	Unique 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.
`effectiveAt`	datetime	No	When the grant becomes effective. Defaults to the entitlement’s current period start.
`expiresAt`	datetime	No	When the grant expires. If omitted, the grant does not expire.
`successUrl`	string	No	URL to redirect the customer to after successful payment.
`cancelUrl`	string	No	URL to redirect the customer to if they cancel payment.
`paymentExpiresAt`	datetime	No	When 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

Field	Type	Description
`object`	string	Always `"grant"`.
`id`	string	Unique identifier (`grt_` prefix).
`entitlementId`	string	The entitlement this grant belongs to.
`amount`	number	The number of credits granted.
`effectiveAt`	datetime	When the grant becomes effective.
`expiresAt`	datetime \| null	When the grant expires. `null` means no expiration.
`voidedAt`	datetime \| null	When the grant was voided. `null` means the grant is active.
`createdAt`	datetime	When 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

Getting Started

Authentication

Platform

Legal

Prerequisites

Creating a Grant (Direct)

Request fields

Purchasing a Grant

Request fields

What happens if payment expires

Managing Grants

List grants

Get a grant

Void a grant

Grant Object

Next Steps

Getting Started

Authentication

Platform

Legal

​Prerequisites

​Creating a Grant (Direct)

​Request fields

​Purchasing a Grant

​Request fields

​What happens if payment expires

​Managing Grants

​List grants

​Get a grant

​Void a grant

​Grant Object

​Next Steps

Prerequisites

Creating a Grant (Direct)

Request fields

Purchasing a Grant

Request fields

What happens if payment expires

Managing Grants

List grants

Get a grant

Void a grant

Grant Object

Next Steps