OpenMeter Entitlements

Create customer entitlement grant

Changed on

Pre-release Endpoint This endpoint is currently in beta and is subject to change.

Issue a grant for a metered entitlement of the customer. Boolean and static entitlements cannot have grants, so the request is rejected for them.

Grants are immutable. The amount is added to the balance from effective_at, which cannot be earlier than the start of the current usage period.

post/v3/openmeter/customers/{customerId}/entitlements/{entitlementId}/grants

Request

  • Base URL: https://global.api.konghq.com
  • URL: https://global.api.konghq.com/v3/openmeter/customers/{customerId}/entitlements/{entitlementId}/grants
  • Auth: one of:
    • HTTP bearer
    • HTTP bearer
    • HTTP bearer
    • HTTP bearer

Path parameters

customerIdstring required

ULID (Universally Unique Lexicographically Sortable Identifier).

Example:01G65Z755AFWAKHE12NY0CQ9FH
entitlementIdstring required

ULID (Universally Unique Lexicographically Sortable Identifier).

Example:01G65Z755AFWAKHE12NY0CQ9FH

Request body

amountstring required

The amount to grant, in the feature's unit. Must be positive.

priorityinteger

The priority of the grant. Lower values have higher priority. Grants are consumed in priority order, then by closest expiration, then by earliest creation.

effective_atstring date-time required

The time the grant becomes effective and the anchor for recurring grants. The value is truncated to the start of the minute.

expires_afterstring ISO8601

The duration after which the grant expires, counted from effective_at. Only single-unit durations are accepted, such as PT12H, P7D, P2W, P3M, or P1Y. If omitted, the grant never expires.

max_rollover_amountstring

The maximum balance carried over at reset. The balance after a reset is MIN(max_rollover_amount, MAX(balance_before_reset, min_rollover_amount)). Defaults to amount.

min_rollover_amountstring

The minimum balance carried over at reset. The balance after a reset is MIN(max_rollover_amount, MAX(balance_before_reset, min_rollover_amount)). Defaults to 0.

labelsobject

Labels store metadata of an entity that can be used for filtering an entity list or for searching across entity types.

Keys must be of length 1-63 characters, and cannot start with "kong", "konnect", "mesh", "kic", or "_".

Example request

{
  "amount": "100",
  "priority": 1,
  "effective_at": "2023-01-01T01:01:01.001Z",
  "expires_after": "P1M",
  "max_rollover_amount": "100",
  "min_rollover_amount": "0",
  "labels": {
    "env": "test"
  },
  "recurrence": {
    "interval": "P1M",
    "anchor": "2023-01-01T01:01:01.001Z"
  }
}

Response

EntitlementGrant created response.

idstring required

ULID (Universally Unique Lexicographically Sortable Identifier).

entitlement_idstring required

The ID of the entitlement the grant belongs to.

customer_idstring

The ID of the customer the grant belongs to.

amountstring required

The granted amount, in the feature's unit.

priorityinteger required

The priority of the grant. Lower values are consumed first: a grant with priority 1 is consumed before one with priority 2. Among equal priorities, the grant closest to expiration is consumed first, then the earliest created.

effective_atstring date-time required

The time the grant takes effect.

expires_afterstring ISO8601

The duration after which the grant expires, counted from effective_at. Always a single-unit duration (for example PT12H, P7D, P2W, P3M, P1Y). Absent when the grant never expires.

expires_atstring date-time

The time the grant expires, calculated from effective_at and expires_after. The grant is no longer in effect from this time. Absent when the grant never expires.

max_rollover_amountstring required

The maximum balance the grant carries over at reset. The balance after a reset is MIN(max_rollover_amount, MAX(balance_before_reset, min_rollover_amount)).

min_rollover_amountstring required

The minimum balance the grant carries over at reset. The balance after a reset is MIN(max_rollover_amount, MAX(balance_before_reset, min_rollover_amount)).

next_recurrencestring date-time

The next time the grant recurs. Absent for non-recurring grants.

voided_atstring date-time

The time the grant was voided. A voided grant is no longer in effect from this time.

labelsobject

Labels store metadata of an entity that can be used for filtering an entity list or for searching across entity types.

Keys must be of length 1-63 characters, and cannot start with "kong", "konnect", "mesh", "kic", or "_".

created_atstring date-time required

An ISO-8601 timestamp representation of entity creation date.

updated_atstring date-time required

An ISO-8601 timestamp representation of entity last update date.

deleted_atstring date-time

An ISO-8601 timestamp representation of entity deletion date.

Example response

{
  "id": "01G65Z755AFWAKHE12NY0CQ9FH",
  "entitlement_id": "01G65Z755AFWAKHE12NY0CQ9FH",
  "customer_id": "01G65Z755AFWAKHE12NY0CQ9FH",
  "amount": "100",
  "priority": 1,
  "effective_at": "2023-01-01T01:01:01.001Z",
  "expires_after": "P1M",
  "expires_at": "2023-02-01T01:01:01.001Z",
  "max_rollover_amount": "100",
  "min_rollover_amount": "0",
  "recurrence": {
    "anchor": "2023-01-01T01:01:01.001Z",
    "interval": "P1M"
  },
  "next_recurrence": "2023-02-01T01:01:01.001Z",
  "voided_at": "2023-01-15T01:01:01.001Z",
  "labels": {
    "env": "test"
  },
  "created_at": "2023-01-01T01:01:01.001Z",
  "updated_at": "2023-01-01T01:01:01.001Z",
  "deleted_at": "2023-01-01T01:01:01.001Z"
}

Changes

  • 7aab863a6daaRevision changes
    • breaking

      added to the / response property oneOf list for the response status

    • warning

      added the new key_invalid enum value to the ////// response property for the response status

    • warning

      added the new unique enum value to the ////// response property for the response status

  • 59663dd13a10Revision changes
    • info

      endpoint added