Sign in

v51

latestOpenAPI 3.0.0Apache 2.0raw.githubusercontent.com2026-08-011534301009.2 KB
Entitlements

Create subject entitlement grant

Grants define a behavior of granting usage for a metered entitlement. They can have complicated recurrence and rollover rules, thanks to which you can define a wide range of access patterns with a single grant, in most cases you don't have to periodically create new grants. You can only issue grants for active metered entitlements.

A grant defines a given amount of usage that can be consumed for the entitlement. The grant is in effect between its effective date and its expiration date. Specifying both is mandatory for new grants.

Grants have a priority setting that determines their order of use. Lower numbers have higher priority, with 0 being the highest priority.

Grants can have a recurrence setting intended to automate the manual reissuing of grants. For example, a daily recurrence is equal to reissuing that same grant every day (ignoring rollover settings).

Rollover settings define what happens to the remaining balance of a grant at a reset. Balance_After_Reset = MIN(MaxRolloverAmount, MAX(Balance_Before_Reset, MinRolloverAmount))

Grants cannot be changed once created, only deleted. This is to ensure that balance is deterministic regardless of when it is queried.

⚠️ Deprecated: Use POST /api/v2/customers/{customerIdOrKey}/entitlements/{entitlementIdOrFeatureKey}/grants instead.

post/api/v1/subjects/{subjectIdOrKey}/entitlements/{entitlementIdOrFeatureKey}/grants

Path parameters

subjectIdOrKeystring required
entitlementIdOrFeatureKeystring required

Request body

amountnumber double required

The amount to grant. Should be a positive number.

priorityinteger

The priority of the grant. Grants with higher priority are applied first. Priority is a positive decimal numbers. With lower numbers indicating higher importance. For example, a priority of 1 is more urgent than a priority of 2. When there are several grants available for the same subject, the system selects the grant with the highest priority. In cases where grants share the same priority level, the grant closest to its expiration will be used first. In the case of two grants have identical priorities and expiration dates, the system will use the grant that was created first.

effectiveAtstring date-time required

Effective date for grants and anchor for recurring grants. Provided value will be ceiled to metering windowSize (minute).

maxRolloverAmountnumber double

Grants are rolled over at reset, after which they can have a different balance compared to what they had before the reset. Balance after the reset is calculated as: Balance_After_Reset = MIN(MaxRolloverAmount, MAX(Balance_Before_Reset, MinRolloverAmount))

minRolloverAmountnumber double

Grants are rolled over at reset, after which they can have a different balance compared to what they had before the reset. Balance after the reset is calculated as: Balance_After_Reset = MIN(MaxRolloverAmount, MAX(Balance_Before_Reset, MinRolloverAmount))

metadataMetadata

Set of key-value pairs. Metadata can be used to store additional information about a resource.

Example request

{
  "amount": 100,
  "priority": 1,
  "effectiveAt": "2023-01-01T01:01:01.001Z",
  "expiration": {
    "count": 12
  },
  "maxRolloverAmount": 100,
  "minRolloverAmount": 100,
  "metadata": {
    "externalId": "019142cc-a016-796a-8113-1a942fecd26d"
  },
  "recurrence": {
    "interval": "DAY",
    "anchor": "2023-01-01T01:01:01.001Z"
  }
}

Response

The request has succeeded and a new resource has been created as a result.

createdAtstring date-time required

Timestamp of when the resource was created.

updatedAtstring date-time required

Timestamp of when the resource was last updated.

deletedAtstring date-time

Timestamp of when the resource was permanently deleted.

amountnumber double required

The amount to grant. Should be a positive number.

priorityinteger

The priority of the grant. Grants with higher priority are applied first. Priority is a positive decimal numbers. With lower numbers indicating higher importance. For example, a priority of 1 is more urgent than a priority of 2. When there are several grants available for the same subject, the system selects the grant with the highest priority. In cases where grants share the same priority level, the grant closest to its expiration will be used first. In the case of two grants have identical priorities and expiration dates, the system will use the grant that was created first.

effectiveAtstring date-time required

Effective date for grants and anchor for recurring grants. Provided value will be ceiled to metering windowSize (minute).

maxRolloverAmountnumber double

Grants are rolled over at reset, after which they can have a different balance compared to what they had before the reset. Balance after the reset is calculated as: Balance_After_Reset = MIN(MaxRolloverAmount, MAX(Balance_Before_Reset, MinRolloverAmount))

minRolloverAmountnumber double

Grants are rolled over at reset, after which they can have a different balance compared to what they had before the reset. Balance after the reset is calculated as: Balance_After_Reset = MIN(MaxRolloverAmount, MAX(Balance_Before_Reset, MinRolloverAmount))

metadataMetadata

Set of key-value pairs. Metadata can be used to store additional information about a resource.

idstring required

Readonly unique ULID identifier.

entitlementIdstring required

The unique entitlement ULID that the grant is associated with.

nextRecurrencestring date-time

The next time the grant will recurr.

expiresAtstring date-time

The time the grant expires.

voidedAtstring date-time

The time the grant was voided.

annotationsAnnotations

Set of key-value pairs managed by the system. Cannot be modified by user.

Example response

{
  "createdAt": "2024-01-01T01:01:01.001Z",
  "updatedAt": "2024-01-01T01:01:01.001Z",
  "deletedAt": "2024-01-01T01:01:01.001Z",
  "amount": 100,
  "priority": 1,
  "effectiveAt": "2023-01-01T01:01:01.001Z",
  "expiration": {
    "count": 12
  },
  "maxRolloverAmount": 100,
  "minRolloverAmount": 100,
  "metadata": {
    "externalId": "019142cc-a016-796a-8113-1a942fecd26d"
  },
  "id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
  "entitlementId": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
  "nextRecurrence": "2023-01-01T01:01:01.001Z",
  "expiresAt": "2023-01-01T01:01:01.001Z",
  "voidedAt": "2023-01-01T01:01:01.001Z",
  "recurrence": {
    "interval": "DAY",
    "intervalISO": "P1D",
    "anchor": "2023-01-01T01:01:01.001Z"
  },
  "annotations": {
    "externalId": "019142cc-a016-796a-8113-1a942fecd26d"
  }
}