Customers and usage attribution

What is a customer?

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 --> UsageEvents2

Use 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": {...}
}

Create a customer

To create a customer in Konnect, do the following:

Customer currency

A customer’s currency is optional. When you set one, it must be a fiat currency. You can select the currency when you create the customer, and then view it on the customer’s details page.

The customer currency is the settlement currency for everything billed to the customer:

  • If the customer has no currency when you start their first paid subscription, Metering & Billing sets it to that subscription’s invoice currency.
  • A customer without a currency can’t be granted credits, because credit purchases settle in the customer’s currency.
  • A plan priced in a custom currency invoices the customer in their fiat currency, with custom-currency charges converted through the currency’s cost basis.

FAQs

One reason why you might not see events in a customer’s invoice is if the event was sent before the subscription was created. Metering & Billing only invoices and meters events that are sent after the subscription is created.

Help us make these docs great!

Kong Developer docs are open source. If you find these useful and want to make them better, contribute today!