Entitlement Events

#Entitlement Balance Change

#Rule

Type: entitlements.balance.threshold

This event type can be used to notify you if a certain amount of the available credits are used for an Entitlement.

These rules only work for Metered entitlements, as only those have balances. They work by considering all the activities that change the balance of an Entitlement (such as entitlement creation, granting and ingested events), and if the predefined threshold or feature filter conditions match, they trigger a new event.

We guarantee that only one event is triggered per Entitlement per threshold.

#Thresholds

The threshold can be specified as a percentage of the total grants or as an exact usage number.

Percentage thresholds state that the notification should be sent if the subject has used a given percent of its available quota.

These two options allow for the following use-cases:

Limit	Use-case
80%	I would want to send a notification email to our customers that they are reaching their quotas.
100%	I would want to block access in our systems based on the event.
200%	In case of a soft-limit Entitlement, I want to be notified of users way over their soft-limit.
10000	The end-user plan only allows for 10000 credit usage, so I would want to block access based on the event.

Balance Change Rules allow multiple thresholds to be set in the same rule, so the notification settings can be centralized.

#Filtering by features

If multiple features are defined in OpenMeter, it might be practical to receive notifications only for one or more Feature or have different Thresholds per Feature.

An Entitlement Balance Change Rule has an optional Feature filter:

If the filter is not specified OpenMeter evaluates the rule for all metered entitlements
If the filter is specified, OpenMeter only evaluates the rule for metered entitlements defined on the specific Features

#Balance changes by granting, voiding grants, and resets

If any activity (granting, entitlement reset) changes the available balance, the thresholds are reevaluated.

The total available credit balance of the subject can increase in case of a grant operation or decrease in case of a grant being voided.

When granting additional credits to an entitlement, the system reevaluates all the thresholds, and if the currently hit threshold changes, a new notification is sent for the lower threshold.

A notification message will be sent if voiding grants push the Entitlement to a higher threshold.

Resetting an entitlement resets the usage. When the usage reaches the first threshold, a new notification is sent.

#Event

The balance notification event will have the type of entitlements.balance.threshold.

An example event payload for an event triggered by reaching a numeric threshold of 2000 on an entitlement is the following:

{
  "data": {
    "entitlement": {
      "createdAt": "2024-08-22T08:43:14.154903Z",
      "currentUsagePeriod": {
        "from": "2024-08-22T08:43:00Z",
        "to": "2024-08-29T08:43:00Z"
      },
      "featureId": "01J5WKAM9FJ4621ARR641JS17Q",
      "featureKey": "llm_tokens",
      "id": "01J5WM25BAXSCBKG2D9NDYJB6S",
      "isSoftLimit": false,
      "isUnlimited": false,
      "issueAfterReset": 2500,
      "issueAfterResetPriority": 1,
      "lastReset": "2024-08-22T08:43:00Z",
      "measureUsageFrom": "2024-08-22T08:43:00Z",
      "preserveOverageAtReset": false,
      "subjectKey": "notification-test-2",
      "type": "metered",
      "updatedAt": "2024-08-22T08:43:14.154904Z",
      "usagePeriod": {
        "anchor": "2024-08-22T08:43:00Z",
        "interval": "WEEK"
      }
    },
    "feature": {
      "createdAt": "2024-08-22T08:30:23.023643Z",
      "id": "01J5WKAM9FJ4621ARR641JS17Q",
      "key": "llm_tokens",
      "meterSlug": "tokens_total",
      "name": "llm_tokens",
      "updatedAt": "2024-08-22T08:30:23.023644Z"
    },
    "subject": {
      "currentPeriodEnd": null,
      "currentPeriodStart": null,
      "displayName": null,
      "id": "01J5WM256DNGXKG2N17AHVXKTD",
      "key": "notification-test-2",
      "metadata": {},
      "stripeCustomerId": null
    },
    "threshold": {
      "type": "NUMBER",
      "value": 2000
    },
    "value": {
      "balance": 254,
      "hasAccess": true,
      "overage": 0,
      "usage": 2369
    }
  },
  "id": "01J5WQFP993XTYM1HAZH3SHP2G",
  "timestamp": "2024-08-22T09:43:03.209883Z",
  "type": "entitlements.balance.threshold"
}

The event contains contextual data. The receiving end can use this contextual data, ensuring that it doesn't have to make additional calls to the OpenMeter APIs to gather it.

#Entitlement Reset

Type: entitlements.reset

This event type notifies you when an Entitlement is reset. Entitlement resets can occur either through a manual action using the Reset API or automatically at the end of the entitlement's current period.

This event type is applicable exclusively to Metered entitlements, as they are the only entitlement type that operates on a recurring period basis.

#Rule

The rule can be configured to filter notifications by specific Features, similar to Entitlement Balance Threshold rules.

When no Feature filter is specified, notifications will be generated for all entitlement reset events across the system.

#Event

The event format is similar to the threshold events:

{
  "data": {
    "entitlement": {
      "createdAt": "2024-08-22T08:43:14.154903Z",
      "currentUsagePeriod": {
        "from": "2024-08-22T08:43:00Z",
        "to": "2024-08-29T08:43:00Z"
      },
      "featureId": "01J5WKAM9FJ4621ARR641JS17Q",
      "featureKey": "llm_tokens",
      "id": "01J5WM25BAXSCBKG2D9NDYJB6S",
      "isSoftLimit": false,
      "isUnlimited": false,
      "issueAfterReset": 2500,
      "issueAfterResetPriority": 1,
      "lastReset": "2024-08-22T08:43:00Z",
      "measureUsageFrom": "2024-08-22T08:43:00Z",
      "preserveOverageAtReset": false,
      "subjectKey": "notification-test-2",
      "type": "metered",
      "updatedAt": "2024-08-22T08:43:14.154904Z",
      "usagePeriod": {
        "anchor": "2024-08-22T08:43:00Z",
        "interval": "WEEK"
      }
    },
    "feature": {
      "createdAt": "2024-08-22T08:30:23.023643Z",
      "id": "01J5WKAM9FJ4621ARR641JS17Q",
      "key": "llm_tokens",
      "meterSlug": "tokens_total",
      "name": "llm_tokens",
      "updatedAt": "2024-08-22T08:30:23.023644Z"
    },
    "subject": {
      "currentPeriodEnd": null,
      "currentPeriodStart": null,
      "displayName": null,
      "id": "01J5WM256DNGXKG2N17AHVXKTD",
      "key": "notification-test-2",
      "metadata": {},
      "stripeCustomerId": null
    },
    "value": {
      "balance": 254,
      "hasAccess": true,
      "overage": 0,
      "usage": 0
    }
  },
  "id": "01J5WQFP993XTYM1HAZH3SHP2G",
  "timestamp": "2024-08-22T09:43:03.209883Z",
  "type": "entitlements.reset"
}

The included value field represents the entitlement values right after the reset have happened.