Customers represent individuals or organizations that subscribe to plans, gain access to features, and are invoiced for their consumption.
Billable events ingested into Metering & Billing always include a subject field that represents metered entities within your system, such as Kong Gateway Consumers, AI Gateway AI Consumers, Dev Portal applications, or generic subjects for entities outside of Konnect.
A customer can have one or many usage attributes assigned, allowing you to group usage and billing. For example, if a customer has multiple departments that are producing usage, you could create two usage attributes for each department that are assigned to one customer.
flowchart TB
%% Left side
Customer[Customer]
Subject[Subject]
UsageEventsLeft[Usage Events]
Customer -->|1:n| Subject
Subject -->|1:n| UsageEventsLeft
%% Right side
ACME[ACME Inc.]
Dept1[Department 1]
Dept2[Department 2]
UsageEvents1[Usage Events]
UsageEvents2[Usage Events]
ACME --> Dept1
ACME --> Dept2
Dept1 --> UsageEvents1
Dept2 --> UsageEvents2Use the following table to help you determine the best way to map your customers to usage attributes:
|
You want to… |
Then use… |
|---|---|
| Attribute AI Gateway token usage to customers. | Consumers |
| Attribute Kong Gateway API request usage to customers. | Consumers |
| Attribute Konnect Dev Portal application requests to customers. | Applications |
| Attribute usage from sources outside of Kong Gateway and Konnect to customers. | Generic subjects |
What is a subject?
Subjects represent the entity that consumes metered resources in Konnect Metering & Billing. Billable events ingested to Metering & Billing have a subject associated with them.
A subject can represent any unique event in your system, such as:
- Customer ID or User ID
- Hostname or IP address
- Service or application name
- Device ID
The subject model is intentionally generic, enabling flexible application across different metering scenarios.
Subject kinds
The Include usage from dropdown in the Metering & Billing UI groups subjects by kinds. Metering & Billing recognizes the following kinds of subjects:
|
Kind |
Represents |
Subject key |
Listed in the UI |
|---|---|---|---|
| Gateway Consumers | A Kong Gateway Consumer |
consumer:<consumer-id>
|
From Konnect, whether or not it has sent events |
| AI Gateway Consumers | An AI Gateway AI Consumer |
consumer:<consumer-id>
|
From Konnect, whether or not it has sent events |
| Dev Portal Applications | A Dev Portal application |
app:<application-id>
|
From Konnect, whether or not it has sent events |
| Generic Subjects |
Any other subject value, such as a user ID or hostname from your own system
|
The value as sent in the event | Only when it has recent events |
Gateway Consumers and AI Gateway Consumers share the consumer: prefix, so the subject key alone doesn’t tell them apart.
Data ingestion
When shipping data to Konnect, you must include the subject within the events payload:
{
"specversion": "1.0",
"type": "api-calls",
"id": "00002",
"time": "2023-01-01T00:00:00.001Z",
"source": "service-0",
"subject": "customer-1",
"data": {...}
}