Skip to content

Commit 6b22143

Browse files
Guariscloudjumpercat
Guaris
and
cloudjumpercat
authored
Feat: Metering and Billing customer entity (#3540)
* subjects * add schema * metering customer * Apply suggestions from code review Co-authored-by: Diana <[email protected]> * Apply suggestions from code review * Delete two subject pages as I moved the content to the customers page Signed-off-by: Diana <[email protected]> --------- Signed-off-by: Diana <[email protected]> Co-authored-by: Diana <[email protected]>
1 parent c72f492 commit 6b22143

File tree

2 files changed

+180
-96
lines changed

2 files changed

+180
-96
lines changed

‎app/metering-and-billing/customer.md‎

Lines changed: 180 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,180 @@
1+
---
2+
title: "Customers and usage attribution"
3+
content_type: reference
4+
description: "Learn how Customers and usage attributes work in {{site.konnect_short_name}} Metering and Billing and how they access features."
5+
layout: reference
6+
products:
7+
- metering-and-billing
8+
tools:
9+
- konnect-api
10+
works_on:
11+
- konnect
12+
breadcrumbs:
13+
- /metering-and-billing/
14+
related_resources:
15+
- text: "{{site.konnect_short_name}} Metering and Billing"
16+
url: /metering-and-billing/
17+
---
18+
19+
## What is a customer?
20+
21+
Customers represent individuals or organizations that subscribe to plans, gain access to features, and are invoiced for their consumption.
22+
23+
Billable events ingested into Metering & Billing always include a subject field that represents metered entities within your system, such as {{site.base_gateway}} [Consumers](/gateway/entities/consumer/), [Dev Portal applications](/dev-portal/self-service/), or [subjects](#what-is-a-subject) or entities outside of {{site.konnect_short_name}}.
24+
25+
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.
26+
27+
{% mermaid %}
28+
flowchart TB
29+
%% Left side
30+
Customer[Customer]
31+
Subject[Subject]
32+
UsageEventsLeft[Usage Events]
33+
34+
Customer -->|1:n| Subject
35+
Subject -->|1:n| UsageEventsLeft
36+
37+
%% Right side
38+
ACME[ACME Inc.]
39+
Dept1[Department 1]
40+
Dept2[Department 2]
41+
UsageEvents1[Usage Events]
42+
UsageEvents2[Usage Events]
43+
44+
ACME --> Dept1
45+
ACME --> Dept2
46+
47+
Dept1 --> UsageEvents1
48+
Dept2 --> UsageEvents2
49+
{% endmermaid %}
50+
51+
Use the following table to help you determine the best way to map your customers to usage attributes:
52+
53+
{% table %}
54+
columns:
55+
- title: You want to...
56+
key: use-case
57+
- title: Then use...
58+
key: recommendation
59+
rows:
60+
- use-case: |
61+
Attribute Kong AI Gateway token usage to customers.
62+
recommendation: "[Consumers](/gateway/entities/consumer/)"
63+
- use-case: |
64+
Attribute {{site.base_gateway}} API request usage to customers.
65+
recommendation: "[Consumers](/gateway/entities/consumer/)"
66+
- use-case: |
67+
Attribute {{site.konnect_short_name}} Dev Portal application requests to customers.
68+
recommendation: "[Applications](/dev-portal/self-service/)"
69+
- use-case: |
70+
Attribute usage from sources outside of {{site.base_gateway}} and {{site.konnect_short_name}} to customers.
71+
recommendation: "[Subjects](#what-is-a-subject)"
72+
{% endtable %}
73+
74+
### What is a subject?
75+
76+
Subjects represent the entity that consumes metered resources in {{site.konnect_short_name}} Metering and Billing. Billable events ingested to Metering and Billing have a subject associated with them.
77+
78+
A subject can represent any unique event in your system, such as:
79+
* Customer ID or User ID
80+
* Hostname or IP address
81+
* Service or application name
82+
* Device ID
83+
84+
The subject model is intentionally generic, enabling flexible application across different metering scenarios.
85+
86+
87+
88+
#### Data ingestion
89+
90+
When shipping data to {{site.konnect_short_name}}, you must include the subject within the events payload:
91+
92+
```ts
93+
{
94+
"specversion": "1.0",
95+
"type": "api-calls",
96+
"id": "00002",
97+
"time": "2023-01-01T00:00:00.001Z",
98+
"source": "service-0",
99+
"subject": "customer-1",
100+
"data": {...}
101+
}
102+
```
103+
104+
## Create a customer
105+
106+
To create a customer in {{site.konnect_short_name}}, do the following:
107+
108+
{% navtabs "customer" %}
109+
{% navtab "Consumer" %}
110+
111+
1. In the {{site.konnect_short_name}} sidebar, click **Metering & Billing**.
112+
1. In the Metering & Billing sidebar, click **Billing**.
113+
1. Click **Create Customer**.
114+
1. In the **Name** field, enter your customer's name.
115+
1. Select **Consumers**.
116+
1. In the **Include usage from** dropdown, search for your Consumer.
117+
1. Click **Save**.
118+
119+
{% endnavtab %}
120+
{% navtab "Application" %}
121+
122+
1. In the {{site.konnect_short_name}} sidebar, click **Metering & Billing**.
123+
1. In the Metering & Billing sidebar, click **Billing**.
124+
1. Click **Create Customer**.
125+
1. In the **Name** field, enter your customer's name.
126+
1. Select **Applications**.
127+
1. In the **Include usage from** dropdown, search for the Dev Portal application.
128+
1. Click **Save**.
129+
130+
{% endnavtab %}
131+
{% navtab "Subject" %}
132+
133+
{:.warning}
134+
> **Important:** During the billing beta, customers are limited to **one subject**. Support for multiple subjects will be available in the future.
135+
136+
Subjects are created when you create the customer. To create a customer associated with a subject, send a `POST` request to the `/api/v1/customers` endpoint:
137+
138+
```
139+
curl https://openmeter.cloud/api/v1/customers \
140+
--request POST \
141+
--header 'Content-Type: application/json' \
142+
--header 'Authorization: Bearer $KONNECT_TOKEN' \
143+
--data '{
144+
"name": "",
145+
"description": "",
146+
"metadata": {
147+
"externalId": "019142cc-a016-796a-8113-1a942fecd26d"
148+
},
149+
"key": "",
150+
"usageAttribution": {
151+
"subjectKeys": [
152+
"$YOUR-SUBJECT"
153+
]
154+
},
155+
"primaryEmail": "",
156+
"currency": "USD",
157+
"billingAddress": {
158+
"country": "US",
159+
"postalCode": "",
160+
"state": "",
161+
"city": "",
162+
"line1": "",
163+
"line2": "",
164+
"phoneNumber": ""
165+
}
166+
}'
167+
```
168+
169+
Replace `$KONNECT_TOKEN` with your [{{site.konnect_short_name}} personal or system access token](/konnect-api/#system-accounts-and-access-tokens).
170+
171+
{:.info}
172+
> {{site.konnect_short_name}} Metering and Billing will also automatically create a subject for you when you ingest an usage event for a new subject.
173+
174+
{% endnavtab %}
175+
{% endnavtabs %}
176+
177+
178+
## Schema
179+
180+
[Insert Schema here](https://openmeter.io/docs/api/cloud#tag/customers)

‎app/metering-and-billing/subjects.md‎

Lines changed: 0 additions & 96 deletions
This file was deleted.

0 commit comments

Comments
 (0)