Entitlements let you control customer access to features defined on a rate card, making it possible to implement complex pricing scenarios such as monthly quotas, prepaid billing, and per-customer pricing.
Entitlements are an attribute of rate cards. You must configure entitlements when configuring a rate card.
Metering & Billing entitlements can help implement various monetization strategies:
|
Use Case |
Description |
|---|---|
| Usage limits | Enforce usage limits like monthly token allowances. |
| Plan variance | Offer tiered plans with different feature sets. |
| Custom quotes | Offer custom quotes and per-customer pricing. |
| Prepaid billing | Adopt prepaid billing and handle top-ups. |
| Commitments | Define and track pre-purchase commitments. |
There are three different types of entitlements:
|
Type |
Description |
|---|---|
| Metered |
Allow customers to consume features up to a certain usage limit. For example, 10 million monthly tokens.
This is useful when the underlying resources are expensive, as is the case for most AI products. Metered entitlements leverage the usage information collected by Metering & Billing and give you the ability to do real-time usage enforcement, as well as historical queries and access checks. When configuring a metered entitlement, you can set the following:
|
| Static |
Define customer-specific configurations as a JSON value.
For example, you could give free users access to a subset of AI models. With static entitlements, you can specify which models the customer can use based on their tier: { "enabledModels": ["gpt-3", "gpt-4"] }.
|
| Boolean |
Describe access to specific features, like SAML SSO, without needing configuration or metering.
In cases where you don’t need to set up usage limits or configure customer-level settings, you can use boolean entitlements. These are simple true or false access grants to a feature.
|
Metered entitlements control access to features where you want to impose usage limits. They leverage the usage information collected by Metering & Billing to enable real-time usage enforcement.
Metered entitlements require a usage period setting that defines the interval over which usage is calculated. This is typically a day, week, or month. In most cases, this should match your customers’ billing cycles.
The start of each period is marked by a reset: at reset, a new marker is set from which usage is queried and aggregated. Metering & Billing automatically executes the reset when a new usage period starts, based on the entitlement configuration.
If you want to maintain a continuous running balance where overage carries forward rather than being forgiven at the end of each period, set the Preserve Overage field on the entitlement. When this is enabled, overage accumulated in the previous period is deducted from the starting balance of the new period.
Static entitlements let you define customer- or plan-specific configuration for a given feature as a JSON value. For example, you could give free trial users access to only a subset of AI models by specifying which models are available based on their tier.
The configuration you pass has to be a JSON-parsable string in object format. For example:
{ "enabledModels": ["gpt-3", "gpt-4"] }
Boolean entitlements are simple true or false access grants to a feature. Use them when you don’t need usage limits or customer-level configuration. For example, you could use a boolean entitlement to grant or deny access to a SAML SSO feature.
Entitlements must be configured as part of rate cards in Konnect. See the Metering & Billing getting started guide for setup steps.
Once configured, you can check entitlements for a customer through the Konnect UI, or using the Metering & Billing /entitlement-access API:
curl -X GET "https://us.api.konghq.com/v3/openmeter/customers/{customerId}/entitlement-access" \
--no-progress-meter --fail-with-body \
-H "Authorization: Bearer $KONNECT_TOKEN"