Create Grant - Paygentic

curl --request POST \ --url https://api.paygentic.io/v1/entitlements/{entitlementId}/grants \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data ' { "amount": 100, "idempotencyKey": "grant-initial-100" } '

{ "object": "grant", "id": "<string>", "entitlementId": "<string>", "amount": 123, "effectiveAt": "2023-11-07T05:31:56Z", "createdAt": "2023-11-07T05:31:56Z", "recurrencePeriod": "<string>", "idempotencyKey": "<string>", "expiresAt": "2023-11-07T05:31:56Z", "voidedAt": "2023-11-07T05:31:56Z", "resetMaxRollover": 123, "resetMinRollover": 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.

idempotencyKey

string

required

Idempotency key to prevent duplicate grants. Must be unique per entitlement.

Maximum string length: 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.

resetMaxRollover

number

Maximum balance carried over at the entitlement's reset boundary. If omitted, the entire 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 successfully created.

object

enum<string>

default:grant

required

Available options:

grant

string

required

Unique identifier for the grant.

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

entitlementId

string

required

The entitlement this grant belongs to.

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

amount

number

required

The number of credits granted.

effectiveAt

string<date-time>

required

When the grant becomes effective.

createdAt

string<date-time>

required

When the grant was created.

recurrencePeriod

string | null

required

The recurrence interval (ISO 8601 duration) if this is a recurring grant. Null for one-time grants.

idempotencyKey

string | null

required

The idempotency key used when creating this grant. Null if not provided.

expiresAt

string<date-time> | null

When the grant expires. Null means no expiration.

voidedAt

string<date-time> | null

When the grant was voided. Null means the grant is active.

resetMaxRollover

number

Maximum balance carried over at the entitlement's reset boundary. A value of 999999999999 represents effectively unlimited rollover (the default for direct and purchase grants). A value of 0 means any remaining balance is discarded at each reset.

resetMinRollover

number

Minimum balance at the entitlement's reset boundary; balances below this are floored up. 0 means no floor.