Metering & Billing

Enterprise only

Overview Examples Guides Configuration reference Changelog

Tags

#monetization

Related Resources

Konnect Metering & Billing

Konnect metering

Meter API requests by Consumer with Metering & Billing

The Metering & Billing plugin allows you to meter API requests and AI token usage for usage-based billing for both Kong Gateway on-prem and Konnect deployments. The plugin supports flexible customer identification, custom pricing dimensions, and fine-grained traffic filtering.

If you’re using Kong Gateway on-prem and want to meter traffic, you must use the Metering & Billing plugin.

For Konnect, you can either use the built-in Metering & Billing event ingestion that uses events from Advanced Analytics or use the Metering & Billing plugin.

Event duplication: Do not use both the Metering & Billing plugin and the Konnect built-in event ingestion in Konnect at the same time. This can result in duplicate events.

The following table can help you determine which to use based on your use case:

Use case	Konnect built-in	Metering & Billing plugin
How do you want to set up event ingestion?	Enabled with one click in the Konnect UI.	Manual plugin configuration.
Who do you want to bill?	Consumer or application.	Consumer, Consumer Group, application, or any request header (for example, `x-customer-id` or `x-tenant-id`).
Do you want to bill based on custom dimensions, like department or priority tier?	Not available.	Yes. Attach any request header or query parameter as a dimension on the event (for example, department, project, priority tier).
How do you want to filter traffic for events?	At the Gateway control plane-level only (all Routes and Services in a control plane).	Filter by Route, Service, or header.
Are you running a self-managed Kong Gateway?	Not available.	You must use the plugin, the built-in service isn’t available.

How it works

The Metering & Billing plugin runs in the Kong Gateway request/response path and emits usage events in CloudEvents format. These events are immutable once emitted and aren’t observability or analytics signals.

For each request, the plugin:

Resolves the subject (the customer identity that gets billed) from the configured source (a Consumer, application, or request header).
Captures standard Kong Gateway metadata on the event, including Route, Service, and response status.
Attaches any configured custom attributes from request headers or query parameters, such as department, project, or priority tier.
Buffers the event locally and delivers it in batches to the configured ingest endpoint (Konnect Metering & Billing or OpenMeter self-hosted), with automatic retries on failure.

Events and subjects

Every usage event has a subject that identifies who is billed for the request. The subject is the most important configuration decision because it determines how usage is grouped and aggregated. You can set the subject to a Kong Gateway Consumer, Konnect Dev Portal application, or any request header value such as x-customer-id or x-tenant-id.

If the plugin can’t resolve a subject from the configured source (for example, if the expected header is missing), the event is dropped.

Filtering traffic and custom dimensions

You can further narrow which traffic and dimensions the plugin will ingest as events. The following table describes how you can configure the plugin to filter traffic or custom dimensions:

Use case	Description	Configuration example
Filtering on custom dimensions	You can use event attributes to capture custom properties for the usage event for pricing dimensions or reporting. Event attributes allow you to filter based on criteria such as provider, department, priority, or project for tiered or per-dimension pricing. You can define any attribute that is found in the header, query, or path of a request.	Set `config.attributes` with the source, what attribute to look up in the source, and which source value to use.
Filtering traffic in a control plane	Since plugins can be applied globally, to Routes, Gateway Services, or Consumers, you can apply the Metering & Billing plugin to these entities to further narrow down the traffic you want to meter from the control plane.	Scope the plugin to a Route, Service, or Consumer.

Buffering and delivery

The plugin buffers events in a local queue before sending them to the ingest endpoint in batches. If delivery fails, the queue retries with exponential backoff up to the configured maximum retry duration. Events that can’t be delivered within that window are dropped. The plugin itself is stateless; it doesn’t persist events across Gateway restarts.

Enforcing entitlements

The Metering & Billing plugin only meters events, it doesn’t enforce metered limits. You must use a rate limiting plugin alongside the Metering & Billing plugin to enforce limits.

For example, if you’re metering AI request tokens to 100 per month, you must use AI Rate Limiting Advanced to limit the tokens.

Usage-based billing

The Metering & Billing plugin can’t bill customers. If you want to bill customers based on usage events from the plugin, use Konnect Metering & Billing or OpenMeter self-hosted.