Customers and usage attribution

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, Dev Portal applications, or subjects or 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:

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.

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

To create a customer in Konnect, do the following:

curl -X POST "https://us.api.konghq.com/v3/openmeter/customers" \
     --no-progress-meter --fail-with-body  \
     -H "Authorization: Bearer $KONNECT_TOKEN" \
     --json '{
       "name": "ACME Inc.",
       "key": "019ae40f-4258-7f15-9491-842f42a7d6ac",
       "usageAttribution": {
         "subjectKeys": [
           "YOUR-SUBJECT-KEY"
         ]
       }
     }'

Insert Schema here