From ea4d91d9676433445ad750cedd3ae017e5187240 Mon Sep 17 00:00:00 2001 From: lena-larionova Date: Wed, 5 Aug 2026 15:12:12 -0700 Subject: [PATCH 1/4] convert m&b guides to use API requests instead of the UI --- .../get-started-with-metering-and-billing.md | 295 ------------------ ...onfigure-metering-and-billing-tax-codes.md | 115 +++++-- .../get-started-with-metering-and-billing.md | 267 ---------------- .../get-started-with-prepaid-credits.md | 134 ++++++-- .../meter-and-bill-active-users.md | 178 +++++++---- 5 files changed, 313 insertions(+), 676 deletions(-) delete mode 100644 app/_how-tos/gateway/get-started-with-metering-and-billing.md delete mode 100644 app/_how-tos/metering-and-billing/get-started-with-metering-and-billing.md diff --git a/app/_how-tos/gateway/get-started-with-metering-and-billing.md b/app/_how-tos/gateway/get-started-with-metering-and-billing.md deleted file mode 100644 index 4f8c15b4e7b..00000000000 --- a/app/_how-tos/gateway/get-started-with-metering-and-billing.md +++ /dev/null @@ -1,295 +0,0 @@ ---- -title: Get started with {{site.metering_and_billing}} in {{site.konnect_short_name}} -description: Learn how to meter and monetize API Gateway requests with {{site.konnect_short_name}} and {{site.metering_and_billing}}. -content_type: how_to - -permalink: /metering-and-billing/get-started/ -breadcrumbs: - - /metering-and-billing/ - -products: - - gateway - - metering-and-billing - -works_on: - - konnect - -tags: - - get-started - -tldr: - q: What is {{site.metering_and_billing}} in {{site.konnect_short_name}}, and how can I get started with it? - a: | - [{{site.metering_and_billing}}](/metering-and-billing/) provides flexible billing and metering for AI and DevTool companies. It also includes real-time insights and usage limit enforcement. - - This tutorial will help you get started with {{site.metering_and_billing}} by setting up metering based on {{site.base_gateway}} API requests, turn raw API usage into billable product offerings by defining features and pricing plans, and start subscriptions to assign to customers. - -tools: - - deck - -prereqs: - entities: - services: - - example-service - routes: - - example-route - inline: - - title: "{{site.konnect_short_name}} roles" - content: | - You need the [{{site.metering_and_billing}} Admin role](/konnect-platform/teams-and-roles/#metering-billing) in {{site.konnect_short_name}} to configure {{site.metering_and_billing}}. - icon_url: /assets/icons/kogo-white.svg - - title: "{{site.konnect_short_name}} system account token" - include_content: prereqs/metering-and-billing-spat - icon_url: /assets/icons/kogo-white.svg - -cleanup: - inline: - - title: Clean up Konnect environment - include_content: cleanup/platform/konnect - icon_url: /assets/icons/gateway.svg -related_resources: - - text: "{{site.base_gateway}}" - url: /gateway/ - - text: Product Catalog reference - url: /metering-and-billing/product-catalog/ - - text: Metering reference - url: /metering-and-billing/metering/ - - text: Customers and usage attribution - url: /metering-and-billing/customer/ - - text: Billing and invoicing - url: /metering-and-billing/billing-invoicing/ - - text: Meter and bill {{site.ai_gateway}} LLM tokens - url: /how-to/meter-llm-traffic/ - - text: Get started with {{site.metering_and_billing}} generic meters - url: /how-to/get-started-with-metering-and-billing-generic-meters/ -min_version: - gateway: '3.4' -next_steps: - - text: See all {{site.base_gateway}} tutorials - url: /how-to/?products=gateway - - text: Learn about {{site.base_gateway}} entities - url: /gateway/entities/ - - text: Learn about how {{site.base_gateway}} is configured - url: /gateway/configuration/ - - text: See all {{site.base_gateway}} plugins - url: /plugins/ -faqs: - - q: I previously enabled metering using the **Enable Gateways** button in the {{site.konnect_short_name}} UI. Do I need to do anything? - a: | - {% include faqs/metering-and-billing-legacy-ingestion.md %} - -automated_tests: false ---- - -This getting-started guide shows how you can meter {{site.base_gateway}} API requests and invoice your customers based on their API consumption with {{site.metering_and_billing}} in {{site.konnect_short_name}}. - -In this guide, you'll: -* Create a {{site.base_gateway}} Consumer that you'll map as a customer -* Set up a meter for {{site.base_gateway}} API requests -* Create a premium plan based on API usage -* Start subscriptions for a customer -* Generate an invoice for a customer on the paid premium plan and see their API usage - -The following diagram shows how {{site.base_gateway}} entities and {{site.metering_and_billing}} entities are associated: - -{% mermaid %} -flowchart TB - subgraph gateway["Kong Gateway"] - direction LR - service["example-service"] - route["example-route"] - consumer1["Consumer-Kong Air"] - end - subgraph metering["Konnect {{site.metering_and_billing}}"] - direction LR - meter["Meter"] - subgraph plan["Premium Plan"] - direction LR - feature2["Feature (example-service)"] - rate-card2["Rate card"] - end - subgraph subscription["Premium Subscription"] - direction LR - customer1["Customer (Kong Air)"] - end - end - gateway --> metering - service --> meter - meter --> feature2 - consumer1 --> customer1 - subscription --> plan - -{% endmermaid %} - - -## Create a Consumer - -Before you configure {{site.metering_and_billing}}, you can set up a Consumer, Kong Air. [Consumers](/gateway/entities/consumer/) let you identify the client that's interacting with {{site.base_gateway}}. Later in this guide, you'll be mapping this Consumer to a customer in {{site.metering_and_billing}} and assigning them to a Premium plan. Doing this allows you map existing Consumers that are already consuming your APIs to customers to make them billable. - -You're going to use key [authentication](/gateway/authentication/) in this tutorial, so the Consumer needs an API key to access any {{site.base_gateway}} Services. - - -{% entity_examples %} -entities: - consumers: - - username: kong-air - keyauth_credentials: - - key: air-key -{% endentity_examples %} - - -## Enable authentication - -Authentication lets you identify a Consumer so you can invoice them as customers after they've consumed the resource, in this case, the API request. -This example uses the [Key Authentication](/plugins/key-auth/) plugin, but you can use any [authentication plugin](/plugins/?category=authentication) that you prefer. - -Enable the plugin globally, which means it applies to all {{site.base_gateway}} Services and Routes: - - -{% entity_examples %} -entities: - plugins: - - name: key-auth - config: - key_names: - - apikey -{% endentity_examples %} - - -## Create a meter - -In {{site.metering_and_billing}}, meters track and record the consumption of a resource or service over time. This usage can take various forms, such as API requests, compute time seconds, or tokens consumed. Usage metering is commonly event-based to ensure accuracy and data you can audit. - -Create a meter to count API requests: - - -{% konnect_api_request %} -url: /v3/openmeter/meters -method: POST -body: - name: API requests - key: api_requests_total - description: Number of API requests - event_type: kong.api_request - aggregation: count - dimensions: - request_method: $.request_method - route_name: $.route_name - service_name: $.service_name -{% endkonnect_api_request %} - - -## Enable the {{site.metering_and_billing}} plugin - -Next, configure the [{{site.metering_and_billing}} plugin](/plugins/metering-and-billing/) to emit API request events from {{site.base_gateway}} to {{site.metering_and_billing}} so that you can charge customers for API traffic usage: - - -{% entity_examples %} -entities: - plugins: - - name: metering-and-billing - service: example-service - config: - ingest_endpoint: https://us.api.konghq.com/v3/openmeter/events - api_token: ${AUTH_TOKEN} - meter_api_requests: true - meter_ai_token_usage: false - subject: - look_up_value_in: consumer -variables: - AUTH_TOKEN: - value: $AUTH_TOKEN - description: A {{site.konnect_short_name}} system account token (`spat_`) with the Metering Ingest role. -{% endentity_examples %} - - -## Create a feature - -Meters collect raw usage data, but features make that data billable. Without a feature, usage is tracked but not invoiced. Now that you're metering API consumption, you need to associate traffic from the `example-service` Gateway Service with a feature as something you want to price or govern. - -Features are customer-facing, and show up on the invoice for paid plans. Feature examples could include things like flight data requests, GPT-5 input tokens, or available LLM models. - -In this guide, you'll create a feature for the `example-service` you created in the prerequisites. - -1. In the {{site.konnect_short_name}} sidebar, click **{{site.metering_and_billing}}**. -1. In the {{site.metering_and_billing}} sidebar, click **Product Catalog**. -1. Click **Create Feature**. -1. In the **Name** field, enter `example-service`. -1. From the **Meter** dropdown menu, select "API requests". -1. Click **Add group by filter**. - The group by filter ensures you only bill for traffic to `example-service`, not all {{site.base_gateway}} traffic. This lets you offer different pricing for different APIs. -1. From the **Group by** dropdown menu, select "service_name". -1. From the **Operator** dropdown menu, select "Equals". -1. In the **Value** dropdown menu, enter "example-service". -1. Click **Save**. - -## Create a Premium plan - -Plans are the core building blocks of your product catalog. They are a collection of rate cards that define the price and access of a feature. Plans can be assigned to customers by starting a subscription. - -A rate card describes price and usage limits or access control for a feature or item. Rate cards are made up of the associated feature, price, and optional usage limits or access control for the feature, called entitlements. - -In this section, you'll create a Premium plan that grants paying customers access to the `example-service` at a rate of 5,000 requests per month: - -1. In the {{site.konnect_short_name}} sidebar, click **{{site.metering_and_billing}}**. -1. In the {{site.metering_and_billing}} sidebar, click **Product Catalog**. -1. Click the **Plans** tab. -1. Click **Create Plan**. -1. In the **Name** field, enter `Premium`. -1. In the **Billing cadence** dropdown menu, select "1 month". -1. Click **Save**. -1. Click **Add Rate Card**. -1. From the **Feature** dropdown menu, select "example-service". -1. Click **Next Step**. -1. From the **Pricing model** dropdown menu, select "Usage based". -1. In the **Price per unit** field, enter `1`. -1. Click **Next Step**. -1. Click **Save Rate Card**. -1. Click **Publish Plan**. - -## Start a subscription - -Customers are the entities who pay for the consumption. In many cases, it's equal to your Consumer. Here you are going to create a customer and map our Consumer to it. - -1. In the {{site.konnect_short_name}} sidebar, click **{{site.metering_and_billing}}**. -1. In the {{site.metering_and_billing}} sidebar, click **Billing**. -1. Click **Create Customer**. -1. In the **Name** field, enter `Kong Air`. -1. In the **Key** field, enter `kong-air`. -1. In the **Include usage from** dropdown, select "kong-air". -1. Click **Save**. -1. Click the **Subscriptions** tab. -1. Click **Create a Subscription**. -1. From the **Subscribed Plan** dropdown, select "Premium". -1. Click **Next Step**. -1. Click **Start Subscription**. - - - -## Validate - -You can run the following command to test the that the Kong Air Consumer is invoiced correctly: - - -```sh -for _ in {1..6}; do - curl -i $KONNECT_PROXY_URL/anything \ - -H "apikey:air-key" - echo -done -``` - - -This will generate six requests. Now, check the invoice that was created in {{site.metering_and_billing}}: - -1. In the {{site.konnect_short_name}} sidebar, click **{{site.metering_and_billing}}**. -1. In the {{site.metering_and_billing}} sidebar, click **Billing**. -1. Click the **Invoices** tab. -1. Click **Kong Air**. -1. Click the **Invoicing** tab. -1. Click **Preview Invoice**. - -You'll see in Lines that `example-service` is listed and was used six times. In this guide, you're using the sandbox for invoices. To deploy your subscription in production, configure a payments integration in **{{site.metering_and_billing}}** > **Settings**. - -{:.info} -> **Entitlement enforcement:** {{site.base_gateway}} does not automatically block traffic when a customer's entitlement is exhausted. To enforce limits, set up a webhook notification rule and cut off access in your own infrastructure. See [Enforcing entitlements](/metering-and-billing/entitlements/#entitlement-enforcement) for details. \ No newline at end of file diff --git a/app/_how-tos/metering-and-billing/configure-metering-and-billing-tax-codes.md b/app/_how-tos/metering-and-billing/configure-metering-and-billing-tax-codes.md index c2fc20493e3..59977bbeb1a 100644 --- a/app/_how-tos/metering-and-billing/configure-metering-and-billing-tax-codes.md +++ b/app/_how-tos/metering-and-billing/configure-metering-and-billing-tax-codes.md @@ -28,6 +28,9 @@ prereqs: content: | You need the [{{site.metering_and_billing}} Admin role](/konnect-platform/teams-and-roles/#metering-billing) in {{site.konnect_short_name}} to configure {{site.metering_and_billing}}. icon_url: /assets/icons/kogo-white.svg + - title: "Plan and subscription" + include_content: prereqs/metering-and-billing-plan-subscription + icon_url: /assets/icons/money.svg cleanup: inline: @@ -74,26 +77,71 @@ For background on how tax codes work and how the fallback chain is evaluated, se When your organization is created, {{site.metering_and_billing}} sets up two defaults: one for invoicing and one for credit grants. Review these before creating custom codes, as the pre-provisioned codes may already cover your needs. -1. In the {{site.konnect_short_name}} sidebar, click **Metering & Billing** > **Settings**. -1. Click the **Tax Codes** tab. -1. Review the list of system-managed and user-created tax codes and the current defaults. -1. To change which code is the default, click the action menu on any row and select **Set as Invoicing Default** or **Set as Credit Grant Default**. +List all tax codes in your organization: + + +{% konnect_api_request %} +url: /v3/openmeter/tax-codes +method: GET +status_code: 200 +{% endkonnect_api_request %} + + +If a system-managed code covers your needs and you want to set it as the default, update the organization defaults. +Replace `TAX_CODE_ID` with the `id` from the list response: + + +{% konnect_api_request %} +url: /v3/openmeter/defaults/tax-codes +method: PUT +status_code: 200 +body: + invoicing_tax_code: + id: TAX_CODE_ID +{% endkonnect_api_request %} + + +Use `credit_grant_tax_code` instead of `invoicing_tax_code` to set the credit grant default. If the system-managed codes cover your needs, you can skip the next step and go directly to [Apply a tax code to a rate card](#apply-a-tax-code-to-a-rate-card). ## Create a tax code -If none of the system-managed codes match your product category, you can create a custom tax code: - -1. In the {{site.konnect_short_name}} sidebar, click **Metering & Billing** > **Settings**. -1. Click the **Tax Codes** tab. -1. Click **Create tax code**. -1. Enter a name, key, and optional description. -1. (Optional) Add one or more app mappings. - For Stripe, the value must follow the `txcd_XXXXXXXX` format. - You can browse available values in the [Stripe Tax Code reference](https://docs.stripe.com/tax/tax-codes). -1. (Optional) Set the code as the **Invoicing Default** or **Credit Grant Default**. -1. Click **Save**. +If none of the system-managed codes match your product category, you can create a custom tax code. + +For Stripe, the `app_mappings` value must follow the `txcd_XXXXXXXX` format. +You can browse available values in the [Stripe Tax Code reference](https://docs.stripe.com/tax/tax-codes). + + +{% konnect_api_request %} +url: /v3/openmeter/tax-codes +method: POST +status_code: 201 +body: + name: Software as a Service + key: saas + description: Tax code for SaaS products + app_mappings: + - app_type: stripe + tax_code: txcd_10000000 +capture: + - variable: TAX_CODE_ID + jq: ".id" +{% endkonnect_api_request %} + + +To set the new code as the invoicing default: + + +{% konnect_api_request %} +url: /v3/openmeter/defaults/tax-codes +method: PUT +status_code: 200 +body: + invoicing_tax_code: + id: $TAX_CODE_ID +{% endkonnect_api_request %} + {:.info} > **Note:** Only one tax code can be set as the default per category at a time. @@ -108,17 +156,40 @@ You can apply a tax code at two levels within your product catalog. This sets the tax code for a specific product or fee, overriding the organization default. -1. In the {{site.konnect_short_name}} sidebar, click **Metering & Billing** > **Product Catalog**. -1. Click the **Plans** or **Add-ons** tab and select a plan or add-on. -1. Open or create a rate card. -1. In the **Pricing Model** configuration, expand **Advanced Settings**. -1. In the **Tax Behavior** dropdown, select the behavior you want to apply. -1. In the **Tax Code** dropdown, select your custom code. -1. Save the rate card. +Update the plan using `$PLAN_ID` from the prerequisites. +The `PUT` endpoint replaces the entire plan, so include all existing rate cards in the request: + + +{% konnect_api_request %} +url: /v3/openmeter/plans/$PLAN_ID +method: PUT +status_code: 200 +body: + name: Example Plan + phases: + - name: default + key: default + rate_cards: + - name: API requests + key: api_requests + feature: + id: $FEATURE_ID + price: + type: unit + amount: "1" + entitlement: + type: boolean + tax_config: + behavior: exclusive + code: + id: $TAX_CODE_ID +{% endkonnect_api_request %} + ### Apply a tax code on a subscription rate card This overrides the tax code for a specific customer's subscription, without changing the underlying plan. +Subscription rate card overrides are only available through the {{site.konnect_short_name}} UI. 1. In the {{site.konnect_short_name}} sidebar, click **Metering & Billing** > **Billing**. 1. Click a customer. diff --git a/app/_how-tos/metering-and-billing/get-started-with-metering-and-billing.md b/app/_how-tos/metering-and-billing/get-started-with-metering-and-billing.md deleted file mode 100644 index d178fb07dbc..00000000000 --- a/app/_how-tos/metering-and-billing/get-started-with-metering-and-billing.md +++ /dev/null @@ -1,267 +0,0 @@ ---- -title: Get started with {{site.metering_and_billing}} generic meters -permalink: /how-to/get-started-with-metering-and-billing-generic-meters/ -description: Learn how to meter and bill AI agent runs using generic metering in {{site.konnect_short_name}} {{site.metering_and_billing}}. -content_type: how_to - -breadcrumbs: - - /metering-and-billing/ - -products: - - metering-and-billing - -works_on: - - konnect - -tags: - - get-started - - metering - - billing - -prereqs: - skip_product: true - inline: - - title: "{{site.konnect_short_name}} roles" - content: | - You need the [{{site.metering_and_billing}} Admin role](/konnect-platform/teams-and-roles/#metering-billing) in {{site.konnect_short_name}} to configure {{site.metering_and_billing}}. - icon_url: /assets/icons/kogo-white.svg - -cleanup: - inline: - - title: Clean up Konnect environment - include_content: cleanup/platform/konnect - icon_url: /assets/icons/gateway.svg - -tldr: - q: How can I meter and bill AI agent runs in {{site.konnect_short_name}}? - a: | - To meter AI agent runs in {{site.konnect_short_name}}, create a generic meter with the **Count agent runs** template and `COUNT` aggregation to count agent run events per billing period. Then define a feature and plan to invoice customers based on their usage. Create a customer that includes usage from a subject and assign the customer to your plan. Finally, send events with the subject associated with the customer to generate an invoice. - -related_resources: - - text: Product Catalog reference - url: /metering-and-billing/product-catalog/ - - text: Metering reference - url: /metering-and-billing/metering/ - - text: Customers and usage attribution - url: /metering-and-billing/customer/ - - text: Billing and invoicing - url: /metering-and-billing/billing-invoicing/ - - text: Meter and bill {{site.base_gateway}} API requests - url: /metering-and-billing/get-started/ - - text: Meter and bill {{site.ai_gateway}} LLM tokens - url: /how-to/meter-llm-traffic/ -faqs: - - q: Why don't I see any events in my customer's invoice? - a: | - {% include faqs/no-events-in-invoice.md %} -automated_tests: false ---- - -Generic metering is a flexible way to meter events from a variety of sources. -This guide shows you how to use generic metering in {{site.metering_and_billing}} by demonstrating how to track and invoice customers based on the number of AI agent runs per month. - -Pay-per-run billing is a common pricing model for AI products where customers are charged for each time an agent executes. -By using the `COUNT` aggregation grouped by `agent_name`, you can track total runs and break down usage by agent type. - -In this guide, you'll: - -* Create a generic meter that counts agent runs -* Create a feature to make that usage billable -* Create a usage-based plan -* Start a subscription for a customer -* Send usage events and validate the invoice - -## Create a meter - -In {{site.metering_and_billing}}, [meters](/metering-and-billing/metering/) track and record the consumption of a resource or service over time. -For billing per agent run, you'll use the built-in **Count agent runs** template, which pre-configures a `COUNT` meter that increments once per `agent_run` event and groups results by `agent_name`. - -1. In the {{site.konnect_short_name}} sidebar, click **{{site.metering_and_billing}}**. -1. Click **Create Meter**. -1. Click the **Templates** dropdown menu. -1. Select **Count agent runs**. -1. Click **Save**. - -The template creates a meter with the following configuration: - - -{% table %} -columns: - - title: Field - key: field - - title: Value - key: value -rows: - - field: Key - value: "`agent_runs_total`" - - field: Event type filter - value: "`agent_run`" - - field: Aggregation - value: "`COUNT`" - - field: Labels to group by - value: "`agent_name`" -{% endtable %} - - -## Create a feature - -Meters collect raw usage data, but [features](/metering-and-billing/product-catalog/#features) make that data billable. -Without a feature, usage is tracked but not invoiced. -Now that you're metering agent runs, you need to associate that meter with a feature. - -1. In the {{site.konnect_short_name}} sidebar, click **{{site.metering_and_billing}}**. -1. In the {{site.metering_and_billing}} sidebar, click **Product Catalog**. -1. Click **Create Feature**. -1. In the **Name** field, enter `Agent Runs`. -1. From the **Meter** dropdown menu, select "Count Agent Runs". -1. Click **Save**. - -## Create a plan and rate card - -Plans are the core building blocks of your [product catalog](/metering-and-billing/product-catalog/). -They are a collection of rate cards that define the price and access of a feature. -Plans can be assigned to customers by starting a subscription. - -A [rate card](/metering-and-billing/product-catalog/#rate-cards) describes the price and usage limits or access control for a feature. -Rate cards are made up of the associated feature, price, and optional entitlements. - -In this section, you'll create an Premium Plan plan that charges customers $1 per agent run per month: - -1. In the {{site.konnect_short_name}} sidebar, click **{{site.metering_and_billing}}**. -1. In the {{site.metering_and_billing}} sidebar, click **Product Catalog**. -1. Click the **Plans** tab. -1. Click **Create Plan**. -1. In the **Name** field, enter `Premium Plan`. -1. From the **Billing cadence** dropdown menu, select "1 month". -1. Click **Save**. -1. Click **Add Rate Card**. -1. From the **Feature** dropdown menu, select "Agent Runs". -1. Click **Next Step**. -1. From the **Pricing model** dropdown menu, select "Usage based". -1. In the **Price per unit** field, enter `1`. - - {:.info} - > We're using $1 here to make it easy to see invoice amount changes in the customer invoice. - > Change this price in a production instance to match your own pricing model. -1. Click **Next Step**. -1. Select **Boolean**. -1. Click **Save Rate Card**. -1. Click **Publish Plan**. -1. Click **Publish**. - -## Start a subscription - -[Customers](/metering-and-billing/customer/) are the entities that pay for consumption. Here you'll create a customer and [subscribe](/metering-and-billing/subscriptions/) them to the Premium Plan plan. - -1. In the {{site.konnect_short_name}} sidebar, click **{{site.metering_and_billing}}**. -1. In the {{site.metering_and_billing}} sidebar, click **Billing**. -1. Click **Create Customer**. -1. In the **Name** field, enter `Acme Inc`. -1. In the **Key** field, enter `acme-inc`. - - This value links incoming usage events to this customer. - Events with `"subject": "acme-inc"` will be attributed to Acme Inc. -1. Click **Save**. -1. Click the **Subscription** tab. -1. Click **Create a Subscription**. -1. From the **Subscribed Plan** dropdown, select `Premium Plan`. -1. Click **Next Step**. -1. Click **Start Subscription**. - -## Validate - -Send usage events to {{site.metering_and_billing}} using the [CloudEvents](https://cloudevents.io/) format. -Each event represents one agent run. The meter counts every event, so three events equal three runs. - -{:.warning} -> **Important:** When you send events, they must have a unique `id`. {{site.metering_and_billing}} deduplicates events with the same `id`. - -1. Export the current time: - ```sh - export EVENT_TIME=$(date -u +%Y-%m-%dT%H:%M:%SZ) - ``` - {{site.metering_and_billing}} only invoices and meters events that are sent _after_ the subscription is created. -1. Send a run event for the `summarizer` agent: -{% capture "run1" %} - -{% konnect_api_request %} -url: /v3/openmeter/events -status_code: 200 -method: POST -headers: - - 'Content-Type: application/cloudevents+json' -body: - specversion: "1.0" - type: agent_run - id: 8655CDD7-0775-4AEA-AF8C-89C47EBC8828 - source: acme-platform - time: $EVENT_TIME - datacontenttype: application/json - subject: acme-inc - data: - agent_name: summarizer -{% endkonnect_api_request %} - -{% endcapture %} -{{ run1 | indent: 3 }} - -1. Send a second run event for the `summarizer` agent: -{% capture "run2" %} - -{% konnect_api_request %} -url: /v3/openmeter/events -status_code: 200 -method: POST -headers: - - 'Content-Type: application/cloudevents+json' -body: - specversion: "1.0" - type: agent_run - id: 3EC7EFD0-5B78-47A4-AE9E-15965675CF95 - source: acme-platform - time: $EVENT_TIME - datacontenttype: application/json - subject: acme-inc - data: - agent_name: summarizer -{% endkonnect_api_request %} - -{% endcapture %} -{{ run2 | indent: 3 }} - -1. Send a run event for the `translator` agent: -{% capture "run3" %} - -{% konnect_api_request %} -url: /v3/openmeter/events -status_code: 200 -method: POST -headers: - - 'Content-Type: application/cloudevents+json' -body: - specversion: "1.0" - type: agent_run - id: 48FC220C-C124-4B73-B378-7DC5CF88DD1A - source: acme-platform - time: $EVENT_TIME - datacontenttype: application/json - subject: acme-inc - data: - agent_name: translator -{% endkonnect_api_request %} - -{% endcapture %} -{{ run3 | indent: 3 }} - -Now check the invoice: - -1. In the {{site.konnect_short_name}} sidebar, click **{{site.metering_and_billing}}**. -1. In the {{site.metering_and_billing}} sidebar, click **Billing**. -1. Click **Acme Inc**. -1. Click the **Invoicing** tab. -1. Click **Preview Invoice**. - -You'll see `agent-runs` listed in Lines with a quantity of `3`, reflecting three agent runs (two for `summarizer` and one for `translator`). - -In this guide, you're using the sandbox for invoices. -To deploy your subscription in production, configure a payments integration in **{{site.metering_and_billing}}** > **Settings**, like [Stripe](/metering-and-billing/stripe-integration/). diff --git a/app/_how-tos/metering-and-billing/get-started-with-prepaid-credits.md b/app/_how-tos/metering-and-billing/get-started-with-prepaid-credits.md index 603f54a0af3..284e343b1bb 100644 --- a/app/_how-tos/metering-and-billing/get-started-with-prepaid-credits.md +++ b/app/_how-tos/metering-and-billing/get-started-with-prepaid-credits.md @@ -26,9 +26,8 @@ prereqs: content: | You need the [{{site.metering_and_billing}} Admin role](/konnect-platform/teams-and-roles/#metering-billing) in {{site.konnect_short_name}} to manage credits. icon_url: /assets/icons/kogo-white.svg - - title: "Configured meter" - content: | - You need a [configured meter](/metering-and-billing/metering/#create-a-meter), such as API Gateway requests or {{site.ai_gateway}} tokens. + - title: "Meter and feature" + include_content: prereqs/metering-and-billing-meter-feature-credits icon_url: /assets/icons/money.svg tldr: @@ -63,62 +62,129 @@ automated_tests: false ## Create a credits-only plan -To charge customers via prepaid credits, define a plan with the `credit_only` settlement mode. +To charge customers via prepaid credits, define a plan and set `settlement_mode: credit_only` on the subscription. All usage settles against credits. If a customer runs out of credits, uncovered usage creates a negative credit balance on the ledger rather than generating an overage invoice. -1. In the {{site.konnect_short_name}} sidebar, click **{{site.metering_and_billing}}**. -1. Click **Product Catalog**. -1. Click the **Plans** tab and create a new plan. -1. In the **Billing** section, configure the **Currency** (for example, `USD`) and set the **Settlement mode** to **Credits only**. -1. Click **Add Rate Card** and select the feature you want to price. -1. Configure a **Usage based** pricing model and set your price per unit. -1. Save the rate card and click **Publish Plan**. +First, create the plan with a rate card: + + +{% konnect_api_request %} +url: /v3/openmeter/plans +method: POST +status_code: 201 +body: + name: Credits Plan + key: credits_plan + currency: USD + billing_cadence: P1M + phases: + - name: default + key: default + rate_cards: + - name: API requests + key: api_requests + feature: + id: $FEATURE_ID + price: + type: unit + amount: "1" + entitlement: + type: boolean +capture: + - variable: PLAN_ID + jq: ".id" +{% endkonnect_api_request %} + + +Then publish the plan: + + +{% konnect_api_request %} +url: /v3/openmeter/plans/$PLAN_ID/publish +method: POST +status_code: 200 +{% endkonnect_api_request %} + ## Create a customer Customers represent the individuals or organizations that subscribe to plans and consume your metered features. -1. In the {{site.konnect_short_name}} sidebar, click **{{site.metering_and_billing}}**. -1. In the {{site.metering_and_billing}} sidebar, click **Billing**. -1. Click **Create Customer**. -1. Enter the customer's **Name**. -1. Map the customer to a **Consumer**, **Application**, or **Subject** to ensure their usage is attributed correctly. -1. Click **Save**. + +{% konnect_api_request %} +url: /v3/openmeter/customers +method: POST +status_code: 201 +body: + name: Acme Inc + key: acme-inc + usage_attribution: + subject_keys: + - acme-inc +capture: + - variable: CUSTOMER_ID + jq: ".id" +{% endkonnect_api_request %} + ## Start a subscription Subscriptions link customers to a pricing model and track their usage against rate cards. - -1. On the customer's details page, click the **Subscriptions** tab. -1. Add a new subscription and select the credits-only plan you created. -1. Choose the start date and finalize the subscription. +Setting `settlement_mode: credit_only` ensures all usage is settled against the customer's credit balance. + + +{% konnect_api_request %} +url: /v3/openmeter/subscriptions +method: POST +status_code: 201 +body: + customer: + id: $CUSTOMER_ID + plan: + key: credits_plan + settlement_mode: credit_only +capture: + - variable: SUBSCRIPTION_ID + jq: ".id" +{% endkonnect_api_request %} + ## Grant prepaid credits Prepaid credits burn down as the customer incurs usage. Issue a grant directly to the customer's balance. -1. On the customer's page, click the **Credits** tab. -1. Click **Grant Credits** and select **New credit grant**. -1. In the **Grant** section, enter the **Credit amount**. -1. In the **Charge** section, select **Promotional / Free** as the charge type. -1. Set the **Credit availability** to **Available immediately on grant**. -1. Optionally, expand **Policies** to set a **Credit draw-down order** to control consumption priority if this customer has multiple grants. -1. Click **Next** to review the **Grant Summary**. -1. Click **Grant credits** to finalize. - + +{% konnect_api_request %} +url: /v3/openmeter/customers/$CUSTOMER_ID/credits/grants +method: POST +status_code: 201 +body: + name: Initial credit grant + currency: USD + amount: "100" + funding_method: none +{% endkonnect_api_request %} + + +Setting `funding_method: none` issues the grant as promotional/free credits with no charge. A `funded` movement is recorded in the customer's transaction history and their settled balance increases immediately. ## Monitor the credit ledger After the grant is issued, the customer's available balance reflects the new credits. -Because this customer is on a `credit_only` plan, metered usage automatically deducts from this balance. +Because this customer is on a `credit_only` subscription, metered usage automatically deducts from this balance. -1. On the customer's page, click the **Credits** tab. -1. Click **Transaction History**. + +{% konnect_api_request %} +url: /v3/openmeter/customers/$CUSTOMER_ID/credits/transactions +method: GET +status_code: 200 +{% endkonnect_api_request %} + -You'll see: +The response includes: * A `funded` movement with a positive amount for the grant you issued. * `consumed` movements with negative amounts as usage charges are applied. diff --git a/app/_how-tos/metering-and-billing/meter-and-bill-active-users.md b/app/_how-tos/metering-and-billing/meter-and-bill-active-users.md index 993575b75e3..803ec0c49c1 100644 --- a/app/_how-tos/metering-and-billing/meter-and-bill-active-users.md +++ b/app/_how-tos/metering-and-billing/meter-and-bill-active-users.md @@ -76,14 +76,20 @@ In {{site.metering_and_billing}}, [meters](/metering-and-billing/metering/) trac For per-seat billing, you'll create a generic meter using the `UNIQUE_COUNT` aggregation. This counts the number of distinct `user_id` values seen within the billing period, so if the same user is active multiple times, they're only counted once. -1. In the {{site.konnect_short_name}} sidebar, click **{{site.metering_and_billing}}**. -1. Click **Create Meter**. -1. In the **Name** field, enter `Active users total`. -1. In the **Description** field, enter `Active Users`. -1. In the **Event Type Filter** field, enter `user_activity`. -1. From the **Aggregation** dropdown menu, select "UNIQUE COUNT". -1. In the **Value property** field, enter `$.user_id`. -1. Click **Save**. + +{% konnect_api_request %} +url: /v3/openmeter/meters +method: POST +status_code: 201 +body: + name: Active users total + key: active_users_total + description: Active Users + event_type: user_activity + aggregation: UNIQUE_COUNT + value_property: $.user_id +{% endkonnect_api_request %} + ## Create a feature @@ -91,12 +97,21 @@ Meters collect raw usage data, but [features](/metering-and-billing/product-cata Without a feature, usage is tracked but not invoiced. Now that you're metering active users, you need to associate that meter with a named, customer-facing feature. -1. In the {{site.konnect_short_name}} sidebar, click **{{site.metering_and_billing}}**. -1. In the {{site.metering_and_billing}} sidebar, click **Product Catalog**. -1. Click **Create Feature**. -1. In the **Name** field, enter `active-users`. -1. From the **Meter** dropdown menu, select "Active users total". -1. Click **Save**. + +{% konnect_api_request %} +url: /v3/openmeter/features +method: POST +status_code: 201 +body: + name: active-users + key: active_users + meter: + key: active_users_total +capture: + - variable: FEATURE_ID + jq: ".id" +{% endkonnect_api_request %} + ## Create a plan and rate card @@ -107,48 +122,91 @@ Plans can be assigned to customers by starting a subscription. A [rate card](/metering-and-billing/product-catalog/#rate-cards) describes the price and usage limits or access control for a feature. Rate cards are made up of the associated feature, price, and optional entitlements. -In this section, you'll create a Per-Seat plan that charges customers $1 per active user per month: - -1. In the {{site.konnect_short_name}} sidebar, click **{{site.metering_and_billing}}**. -1. In the {{site.metering_and_billing}} sidebar, click **Product Catalog**. -1. Click the **Plans** tab. -1. Click **Create Plan**. -1. In the **Name** field, enter `Per-Seat`. -1. From the **Billing cadence** dropdown menu, select **1 month**. -1. Click **Save**. -1. Click **Add Rate Card**. -1. From the **Feature** dropdown menu, select "active-users". -1. Click **Next Step**. -1. From the **Pricing model** dropdown menu, select **Usage based**. -1. In the **Price per unit** field, enter `1`. - - {:.info} - > We're using $1 here to make it easy to see invoice amount changes in the customer invoice. - > Change this price in a production instance to match your own pricing model. -1. Click **Next Step**. -1. Select **Boolean**. -1. Click **Save Rate Card**. -1. Click **Publish Plan**. -1. Click **Publish**. +In this section, you'll create a Per-Seat plan that charges customers $1 per active user per month. + +First, create the plan with a rate card: + + +{% konnect_api_request %} +url: /v3/openmeter/plans +method: POST +status_code: 201 +body: + name: Per-Seat + key: per_seat + currency: USD + billing_cadence: P1M + phases: + - name: default + key: default + rate_cards: + - name: active-users + key: active_users + feature: + id: $FEATURE_ID + price: + type: unit + amount: "1" + entitlement: + type: boolean +capture: + - variable: PLAN_ID + jq: ".id" +{% endkonnect_api_request %} + + +{:.info} +> **Note:** We're using $1 here to make it easy to see invoice amount changes in the customer invoice. +> Change this price in a production instance to match your own pricing model. + +Then publish the plan to make it available for subscriptions: + + +{% konnect_api_request %} +url: /v3/openmeter/plans/$PLAN_ID/publish +method: POST +status_code: 200 +{% endkonnect_api_request %} + ## Start a subscription [Customers](/metering-and-billing/customer/) are the entities that pay for consumption. Here you'll create a customer and [subscribe](/metering-and-billing/subscriptions/) them to the Per-Seat plan. -1. In the {{site.konnect_short_name}} sidebar, click **{{site.metering_and_billing}}**. -1. In the {{site.metering_and_billing}} sidebar, click **Billing**. -1. Click **Create Customer**. -1. In the **Name** field, enter `Acme Inc`. -1. In the **Key** field, enter `acme-inc`. - - This value links incoming usage events to this customer. - Events with `"subject": "acme-inc"` will be attributed to Acme Inc. -1. Click **Save**. -1. Click the **Subscription** tab. -1. Click **Create a Subscription**. -1. From the **Subscribed Plan** dropdown, select `Per-Seat`. -1. Click **Next Step**. -1. Click **Start Subscription**. +First, create the customer. +The `key` field links incoming usage events to this customer: events with `"subject": "acme-inc"` will be attributed to Acme Inc. + + +{% konnect_api_request %} +url: /v3/openmeter/customers +method: POST +status_code: 201 +body: + name: Acme Inc + key: acme-inc + usage_attribution: + subject_keys: + - acme-inc +capture: + - variable: CUSTOMER_ID + jq: ".id" +{% endkonnect_api_request %} + + +Then start a subscription to the Per-Seat plan: + + +{% konnect_api_request %} +url: /v3/openmeter/subscriptions +method: POST +status_code: 201 +body: + customer: + id: $CUSTOMER_ID + plan: + key: per_seat +{% endkonnect_api_request %} + ## Validate @@ -261,15 +319,19 @@ body: {% endcapture %} {{ alice2 | indent: 3 }} -Even though four events were sent, the meter counted only three unique users. Now check the invoice: +Even though four events were sent, the meter counted only three unique users. Now check the usage charges: + + +{% konnect_api_request %} +url: /v3/openmeter/customers/$CUSTOMER_ID/charges?expand[]=real_time_usage +method: GET +status_code: 200 +{% endkonnect_api_request %} + -1. In the {{site.konnect_short_name}} sidebar, click **{{site.metering_and_billing}}**. -1. In the {{site.metering_and_billing}} sidebar, click **Billing**. -1. Click **Acme Inc**. -1. Click the **Invoicing** tab. -1. Click **Preview Invoice**. +The response includes a usage-based charge for `active-users` with a `real_time_usage` quantity of `3`, reflecting three unique active users. -You'll see `active-users` listed in Lines with a quantity of `3`, reflecting three unique active users. +To preview the full formatted invoice, go to **{{site.metering_and_billing}}** > **Billing** > **Acme Inc** > **Invoicing** > **Preview Invoice** in the {{site.konnect_short_name}} UI. In this guide, you're using the sandbox for invoices. To deploy your subscription in production, configure a payments integration in **{{site.metering_and_billing}}** > **Settings**, like [Stripe](/metering-and-billing/stripe-integration/). From c9fa3480e69fb51c7df08eee6ee59d9613500e2c Mon Sep 17 00:00:00 2001 From: lena-larionova Date: Wed, 5 Aug 2026 15:12:17 -0700 Subject: [PATCH 2/4] convert m&b guides to use API requests instead of the UI --- .../get-started-with-ai-agent-metering.md | 332 ++++++++++++++++ .../metering-and-billing/get-started.md | 353 ++++++++++++++++++ ...ering-and-billing-meter-feature-credits.md | 34 ++ .../metering-and-billing-plan-subscription.md | 112 ++++++ 4 files changed, 831 insertions(+) create mode 100644 app/_how-tos/metering-and-billing/get-started-with-ai-agent-metering.md create mode 100644 app/_how-tos/metering-and-billing/get-started.md create mode 100644 app/_includes/prereqs/metering-and-billing-meter-feature-credits.md create mode 100644 app/_includes/prereqs/metering-and-billing-plan-subscription.md diff --git a/app/_how-tos/metering-and-billing/get-started-with-ai-agent-metering.md b/app/_how-tos/metering-and-billing/get-started-with-ai-agent-metering.md new file mode 100644 index 00000000000..c4fc78a9613 --- /dev/null +++ b/app/_how-tos/metering-and-billing/get-started-with-ai-agent-metering.md @@ -0,0 +1,332 @@ +--- +title: Get started with {{site.metering_and_billing}} generic meters +permalink: /how-to/get-started-with-metering-and-billing-generic-meters/ +description: Learn how to meter and bill AI agent runs using generic metering in {{site.konnect_short_name}} {{site.metering_and_billing}}. +content_type: how_to + +breadcrumbs: + - /metering-and-billing/ + +products: + - metering-and-billing + +works_on: + - konnect + +tags: + - get-started + - metering + - billing + +prereqs: + skip_product: true + inline: + - title: "{{site.konnect_short_name}} roles" + content: | + You need the [{{site.metering_and_billing}} Admin role](/konnect-platform/teams-and-roles/#metering-billing) in {{site.konnect_short_name}} to configure {{site.metering_and_billing}}. + icon_url: /assets/icons/kogo-white.svg + +cleanup: + inline: + - title: Clean up Konnect environment + include_content: cleanup/platform/konnect + icon_url: /assets/icons/gateway.svg + +tldr: + q: How can I meter and bill AI agent runs in {{site.konnect_short_name}}? + a: | + To meter AI agent runs in {{site.konnect_short_name}}, create a generic meter with the **Count agent runs** template and `COUNT` aggregation to count agent run events per billing period. Then define a feature and plan to invoice customers based on their usage. Create a customer that includes usage from a subject and assign the customer to your plan. Finally, send events with the subject associated with the customer to generate an invoice. + +related_resources: + - text: Product Catalog reference + url: /metering-and-billing/product-catalog/ + - text: Metering reference + url: /metering-and-billing/metering/ + - text: Customers and usage attribution + url: /metering-and-billing/customer/ + - text: Billing and invoicing + url: /metering-and-billing/billing-invoicing/ + - text: Meter and bill {{site.base_gateway}} API requests + url: /metering-and-billing/get-started/ + - text: Meter and bill {{site.ai_gateway}} LLM tokens + url: /how-to/meter-llm-traffic/ +faqs: + - q: Why don't I see any events in my customer's invoice? + a: | + {% include faqs/no-events-in-invoice.md %} +automated_tests: false +--- + +Generic metering is a flexible way to meter events from a variety of sources. +This guide shows you how to use generic metering in {{site.metering_and_billing}} by demonstrating how to track and invoice customers based on the number of AI agent runs per month. + +Pay-per-run billing is a common pricing model for AI products where customers are charged for each time an agent executes. +By using the `COUNT` aggregation grouped by `agent_name`, you can track total runs and break down usage by agent type. + +In this guide, you'll: + +* Create a generic meter that counts agent runs +* Create a feature to make that usage billable +* Create a usage-based plan +* Start a subscription for a customer +* Send usage events and validate the invoice + +## Create a meter + +In {{site.metering_and_billing}}, [meters](/metering-and-billing/metering/) track and record the consumption of a resource or service over time. +For billing per agent run, you'll use the built-in **Count agent runs** template, which pre-configures a `COUNT` meter that increments once per `agent_run` event and groups results by `agent_name`. + + +{% konnect_api_request %} +url: /v3/openmeter/meters +method: POST +status_code: 201 +body: + name: Count Agent Runs + key: agent_runs_total + event_type: agent_run + aggregation: COUNT + dimensions: + agent_name: $.data.agent_name +{% endkonnect_api_request %} + + +This creates a meter with the following configuration: + + +{% table %} +columns: + - title: Field + key: field + - title: Value + key: value +rows: + - field: Key + value: "`agent_runs_total`" + - field: Event type filter + value: "`agent_run`" + - field: Aggregation + value: "`COUNT`" + - field: Labels to group by + value: "`agent_name`" +{% endtable %} + + +## Create a feature + +Meters collect raw usage data, but [features](/metering-and-billing/product-catalog/#features) make that data billable. +Without a feature, usage is tracked but not invoiced. +Now that you're metering agent runs, you need to associate that meter with a feature. + + +{% konnect_api_request %} +url: /v3/openmeter/features +method: POST +status_code: 201 +body: + name: Agent Runs + key: agent_runs + meter: + key: agent_runs_total +capture: + - variable: FEATURE_ID + jq: ".id" +{% endkonnect_api_request %} + + +## Create a plan and rate card + +Plans are the core building blocks of your [product catalog](/metering-and-billing/product-catalog/). +They are a collection of rate cards that define the price and access of a feature. +Plans can be assigned to customers by starting a subscription. + +A [rate card](/metering-and-billing/product-catalog/#rate-cards) describes the price and usage limits or access control for a feature. +Rate cards are made up of the associated feature, price, and optional entitlements. + +In this section, you'll create a Premium Plan that charges customers $1 per agent run per month. + +First, create the plan with a rate card: + + +{% konnect_api_request %} +url: /v3/openmeter/plans +method: POST +status_code: 201 +body: + name: Premium Plan + key: premium_plan + currency: USD + billing_cadence: P1M + phases: + - name: default + key: default + rate_cards: + - name: Agent Runs + key: agent_runs + feature: + id: $FEATURE_ID + price: + type: unit + amount: "1" + entitlement: + type: boolean +capture: + - variable: PLAN_ID + jq: ".id" +{% endkonnect_api_request %} + + +{:.info} +> **Note:** We're using $1 here to make it easy to see invoice amount changes in the customer invoice. +> Change this price in a production instance to match your own pricing model. + +Then publish the plan to make it available for subscriptions: + + +{% konnect_api_request %} +url: /v3/openmeter/plans/$PLAN_ID/publish +method: POST +status_code: 200 +{% endkonnect_api_request %} + + +## Start a subscription + +[Customers](/metering-and-billing/customer/) are the entities that pay for consumption. Here you'll create a customer and [subscribe](/metering-and-billing/subscriptions/) them to the Premium Plan plan. + +First, create the customer. +The `key` field links incoming usage events to this customer: events with `"subject": "acme-inc"` will be attributed to Acme Inc. + + +{% konnect_api_request %} +url: /v3/openmeter/customers +method: POST +status_code: 201 +body: + name: Acme Inc + key: acme-inc + usage_attribution: + subject_keys: + - acme-inc +capture: + - variable: CUSTOMER_ID + jq: ".id" +{% endkonnect_api_request %} + + +Then start a subscription to the Premium Plan: + + +{% konnect_api_request %} +url: /v3/openmeter/subscriptions +method: POST +status_code: 201 +body: + customer: + id: $CUSTOMER_ID + plan: + key: premium_plan +{% endkonnect_api_request %} + + +## Validate + +Send usage events to {{site.metering_and_billing}} using the [CloudEvents](https://cloudevents.io/) format. +Each event represents one agent run. The meter counts every event, so three events equal three runs. + +{:.warning} +> **Important:** When you send events, they must have a unique `id`. {{site.metering_and_billing}} deduplicates events with the same `id`. + +1. Export the current time: + ```sh + export EVENT_TIME=$(date -u +%Y-%m-%dT%H:%M:%SZ) + ``` + {{site.metering_and_billing}} only invoices and meters events that are sent _after_ the subscription is created. +1. Send a run event for the `summarizer` agent: +{% capture "run1" %} + +{% konnect_api_request %} +url: /v3/openmeter/events +status_code: 200 +method: POST +headers: + - 'Content-Type: application/cloudevents+json' +body: + specversion: "1.0" + type: agent_run + id: 8655CDD7-0775-4AEA-AF8C-89C47EBC8828 + source: acme-platform + time: $EVENT_TIME + datacontenttype: application/json + subject: acme-inc + data: + agent_name: summarizer +{% endkonnect_api_request %} + +{% endcapture %} +{{ run1 | indent: 3 }} + +1. Send a second run event for the `summarizer` agent: +{% capture "run2" %} + +{% konnect_api_request %} +url: /v3/openmeter/events +status_code: 200 +method: POST +headers: + - 'Content-Type: application/cloudevents+json' +body: + specversion: "1.0" + type: agent_run + id: 3EC7EFD0-5B78-47A4-AE9E-15965675CF95 + source: acme-platform + time: $EVENT_TIME + datacontenttype: application/json + subject: acme-inc + data: + agent_name: summarizer +{% endkonnect_api_request %} + +{% endcapture %} +{{ run2 | indent: 3 }} + +1. Send a run event for the `translator` agent: +{% capture "run3" %} + +{% konnect_api_request %} +url: /v3/openmeter/events +status_code: 200 +method: POST +headers: + - 'Content-Type: application/cloudevents+json' +body: + specversion: "1.0" + type: agent_run + id: 48FC220C-C124-4B73-B378-7DC5CF88DD1A + source: acme-platform + time: $EVENT_TIME + datacontenttype: application/json + subject: acme-inc + data: + agent_name: translator +{% endkonnect_api_request %} + +{% endcapture %} +{{ run3 | indent: 3 }} + +Now check the usage charges: + + +{% konnect_api_request %} +url: /v3/openmeter/customers/$CUSTOMER_ID/charges?expand[]=real_time_usage +method: GET +status_code: 200 +{% endkonnect_api_request %} + + +The response includes a usage-based charge for `agent-runs` with a `real_time_usage` quantity of `3`, reflecting three agent runs (two for `summarizer` and one for `translator`). + +To preview the full formatted invoice, go to **{{site.metering_and_billing}}** > **Billing** > **Acme Inc** > **Invoicing** > **Preview Invoice** in the {{site.konnect_short_name}} UI. + +In this guide, you're using the sandbox for invoices. +To deploy your subscription in production, configure a payments integration in **{{site.metering_and_billing}}** > **Settings**, like [Stripe](/metering-and-billing/stripe-integration/). diff --git a/app/_how-tos/metering-and-billing/get-started.md b/app/_how-tos/metering-and-billing/get-started.md new file mode 100644 index 00000000000..70633a17609 --- /dev/null +++ b/app/_how-tos/metering-and-billing/get-started.md @@ -0,0 +1,353 @@ +--- +title: Get started with {{site.metering_and_billing}} in {{site.konnect_short_name}} +description: Learn how to meter and monetize API Gateway requests with {{site.konnect_short_name}} and {{site.metering_and_billing}}. +content_type: how_to + +permalink: /metering-and-billing/get-started/ +breadcrumbs: + - /metering-and-billing/ + +products: + - gateway + - metering-and-billing + +works_on: + - konnect + +tags: + - get-started + +tldr: + q: What is {{site.metering_and_billing}} in {{site.konnect_short_name}}, and how can I get started with it? + a: | + [{{site.metering_and_billing}}](/metering-and-billing/) provides flexible billing and metering for AI and DevTool companies. It also includes real-time insights and usage limit enforcement. + + This tutorial will help you get started with {{site.metering_and_billing}} by setting up metering based on {{site.base_gateway}} API requests, turn raw API usage into billable product offerings by defining features and pricing plans, and start subscriptions to assign to customers. + +tools: + - deck + +prereqs: + entities: + services: + - example-service + routes: + - example-route + inline: + - title: "{{site.konnect_short_name}} roles" + content: | + You need the [{{site.metering_and_billing}} Admin role](/konnect-platform/teams-and-roles/#metering-billing) in {{site.konnect_short_name}} to configure {{site.metering_and_billing}}. + icon_url: /assets/icons/kogo-white.svg + - title: "{{site.konnect_short_name}} system account token" + include_content: prereqs/metering-and-billing-spat + icon_url: /assets/icons/kogo-white.svg + +cleanup: + inline: + - title: Clean up Konnect environment + include_content: cleanup/platform/konnect + icon_url: /assets/icons/gateway.svg +related_resources: + - text: "{{site.base_gateway}}" + url: /gateway/ + - text: Product Catalog reference + url: /metering-and-billing/product-catalog/ + - text: Metering reference + url: /metering-and-billing/metering/ + - text: Customers and usage attribution + url: /metering-and-billing/customer/ + - text: Billing and invoicing + url: /metering-and-billing/billing-invoicing/ + - text: Meter and bill {{site.ai_gateway}} LLM tokens + url: /how-to/meter-llm-traffic/ + - text: Get started with {{site.metering_and_billing}} generic meters + url: /how-to/get-started-with-metering-and-billing-generic-meters/ +min_version: + gateway: '3.4' +next_steps: + - text: See all {{site.base_gateway}} tutorials + url: /how-to/?products=gateway + - text: Learn about {{site.base_gateway}} entities + url: /gateway/entities/ + - text: Learn about how {{site.base_gateway}} is configured + url: /gateway/configuration/ + - text: See all {{site.base_gateway}} plugins + url: /plugins/ +faqs: + - q: I previously enabled metering using the **Enable Gateways** button in the {{site.konnect_short_name}} UI. Do I need to do anything? + a: | + {% include faqs/metering-and-billing-legacy-ingestion.md %} + +automated_tests: false +--- + +This getting-started guide shows how you can meter {{site.base_gateway}} API requests and invoice your customers based on their API consumption with {{site.metering_and_billing}} in {{site.konnect_short_name}}. + +In this guide, you'll: +* Create a {{site.base_gateway}} Consumer that you'll map as a customer +* Set up a meter for {{site.base_gateway}} API requests +* Create a premium plan based on API usage +* Start subscriptions for a customer +* Generate an invoice for a customer on the paid premium plan and see their API usage + +The following diagram shows how {{site.base_gateway}} entities and {{site.metering_and_billing}} entities are associated: + +{% mermaid %} +flowchart TB + subgraph gateway["Kong Gateway"] + direction LR + service["example-service"] + route["example-route"] + consumer1["Consumer-Kong Air"] + end + subgraph metering["Konnect {{site.metering_and_billing}}"] + direction LR + meter["Meter"] + subgraph plan["Premium Plan"] + direction LR + feature2["Feature (example-service)"] + rate-card2["Rate card"] + end + subgraph subscription["Premium Subscription"] + direction LR + customer1["Customer (Kong Air)"] + end + end + gateway --> metering + service --> meter + meter --> feature2 + consumer1 --> customer1 + subscription --> plan + +{% endmermaid %} + + +## Create a Consumer + +Before you configure {{site.metering_and_billing}}, you can set up a Consumer, Kong Air. [Consumers](/gateway/entities/consumer/) let you identify the client that's interacting with {{site.base_gateway}}. Later in this guide, you'll be mapping this Consumer to a customer in {{site.metering_and_billing}} and assigning them to a Premium plan. Doing this allows you map existing Consumers that are already consuming your APIs to customers to make them billable. + +You're going to use key [authentication](/gateway/authentication/) in this tutorial, so the Consumer needs an API key to access any {{site.base_gateway}} Services. + + +{% entity_examples %} +entities: + consumers: + - username: kong-air + keyauth_credentials: + - key: air-key +{% endentity_examples %} + + +## Enable authentication + +Authentication lets you identify a Consumer so you can invoice them as customers after they've consumed the resource, in this case, the API request. +This example uses the [Key Authentication](/plugins/key-auth/) plugin, but you can use any [authentication plugin](/plugins/?category=authentication) that you prefer. + +Enable the plugin globally, which means it applies to all {{site.base_gateway}} Services and Routes: + + +{% entity_examples %} +entities: + plugins: + - name: key-auth + config: + key_names: + - apikey +{% endentity_examples %} + + +## Create a meter + +In {{site.metering_and_billing}}, meters track and record the consumption of a resource or service over time. This usage can take various forms, such as API requests, compute time seconds, or tokens consumed. Usage metering is commonly event-based to ensure accuracy and data you can audit. + +Create a meter to count API requests: + + +{% konnect_api_request %} +url: /v3/openmeter/meters +method: POST +body: + name: Total API requests + key: api_requests_total + description: API Requests + event_type: request + aggregation: count + dimensions: + method: $.method + route: $.route +{% endkonnect_api_request %} + + +## Enable the {{site.metering_and_billing}} plugin + +Next, configure the [{{site.metering_and_billing}} plugin](/plugins/metering-and-billing/) to emit API request events from {{site.base_gateway}} to {{site.metering_and_billing}} so that you can charge customers for API traffic usage: + + +{% entity_examples %} +entities: + plugins: + - name: metering-and-billing + service: example-service + config: + ingest_endpoint: https://us.api.konghq.com/v3/openmeter/events + api_token: ${AUTH_TOKEN} + meter_api_requests: true + meter_ai_token_usage: false + subject: + look_up_value_in: consumer +variables: + AUTH_TOKEN: + value: $AUTH_TOKEN + description: A {{site.konnect_short_name}} system account token (`spat_`) with the Metering Ingest role. +{% endentity_examples %} + + +## Create a feature + +Meters collect raw usage data, but features make that data billable. Without a feature, usage is tracked but not invoiced. Now that you're metering API consumption, you need to associate traffic from the `example-service` Gateway Service with a feature as something you want to price or govern. + +Features are customer-facing, and show up on the invoice for paid plans. Feature examples could include things like flight data requests, GPT-5 input tokens, or available LLM models. + +In this guide, you'll create a feature for the `example-service` you created in the prerequisites. + + +{% konnect_api_request %} +url: /v3/openmeter/features +method: POST +status_code: 201 +body: + name: example-service + key: example_service + meter: + key: api_requests_total + filters: + service_name: example-service +capture: + - variable: FEATURE_ID + jq: ".id" +{% endkonnect_api_request %} + + +The `meter.filters` field ensures you only bill for traffic to `example-service`, not all {{site.base_gateway}} traffic. +This lets you offer different pricing for different APIs. + +## Create a Premium plan + +Plans are the core building blocks of your product catalog. They are a collection of rate cards that define the price and access of a feature. Plans can be assigned to customers by starting a subscription. + +A rate card describes price and usage limits or access control for a feature or item. Rate cards are made up of the associated feature, price, and optional usage limits or access control for the feature, called entitlements. + +In this section, you'll create a Premium plan that grants paying customers access to the `example-service` at a rate of 5,000 requests per month. + +First, create the plan with a rate card: + + +{% konnect_api_request %} +url: /v3/openmeter/plans +method: POST +status_code: 201 +body: + name: Premium + key: premium + currency: USD + billing_cadence: P1M + phases: + - name: default + key: default + rate_cards: + - name: example-service + key: example_service + feature: + id: $FEATURE_ID + price: + type: unit + amount: "1" +capture: + - variable: PLAN_ID + jq: ".id" +{% endkonnect_api_request %} + + +Then publish the plan to make it available for subscriptions: + + +{% konnect_api_request %} +url: /v3/openmeter/plans/$PLAN_ID/publish +method: POST +status_code: 200 +{% endkonnect_api_request %} + + +## Start a subscription + +Customers are the entities who pay for the consumption. In many cases, it's equal to your Consumer. Here you are going to create a customer and map our Consumer to it. + +First, create the customer and link it to the `kong-air` Consumer: + + +{% konnect_api_request %} +url: /v3/openmeter/customers +method: POST +status_code: 201 +body: + name: Kong Air + key: kong-air + usage_attribution: + subject_keys: + - kong-air +capture: + - variable: CUSTOMER_ID + jq: ".id" +{% endkonnect_api_request %} + + +Then start a subscription to the Premium plan: + + +{% konnect_api_request %} +url: /v3/openmeter/subscriptions +method: POST +status_code: 201 +body: + customer: + id: $CUSTOMER_ID + plan: + key: premium +{% endkonnect_api_request %} + + +{:.info} +> Note: Want to delete a customer? Cancel their subscription first and then you can delete them. + +## Validate + +You can run the following command to test the that the Kong Air Consumer is invoiced correctly: + + +```sh +for _ in {1..6}; do + curl -i $KONNECT_PROXY_URL/anything \ + -H "apikey:air-key" + echo +done +``` + + +This will generate six requests. Now check the usage charges: + + +{% konnect_api_request %} +url: /v3/openmeter/customers/$CUSTOMER_ID/charges?expand[]=real_time_usage +method: GET +status_code: 200 +{% endkonnect_api_request %} + + +The response includes a usage-based charge for `example-service` with a `real_time_usage` quantity of `6`. + +To preview the full formatted invoice, go to **{{site.metering_and_billing}}** > **Billing** > **Kong Air** > **Invoicing** > **Preview Invoice** in the {{site.konnect_short_name}} UI. + +In this guide, you're using the sandbox for invoices. To deploy your subscription in production, configure a payments integration in **{{site.metering_and_billing}}** > **Settings**. + +{:.info} +> **Entitlement enforcement:** {{site.base_gateway}} does not automatically block traffic when a customer's entitlement is exhausted. To enforce limits, set up a webhook notification rule and cut off access in your own infrastructure. See [Enforcing entitlements](/metering-and-billing/entitlements/#entitlement-enforcement) for details. \ No newline at end of file diff --git a/app/_includes/prereqs/metering-and-billing-meter-feature-credits.md b/app/_includes/prereqs/metering-and-billing-meter-feature-credits.md new file mode 100644 index 00000000000..a5250290cde --- /dev/null +++ b/app/_includes/prereqs/metering-and-billing-meter-feature-credits.md @@ -0,0 +1,34 @@ +Create a meter to count events and a feature to make that usage billable. + +1. Create a meter: + + + {% konnect_api_request %} + url: /v3/openmeter/meters + method: POST + status_code: 201 + body: + name: API requests total + key: api_requests_total + event_type: request + aggregation: COUNT + {% endkonnect_api_request %} + + +1. Create a feature linked to the meter: + + + {% konnect_api_request %} + url: /v3/openmeter/features + method: POST + status_code: 201 + body: + name: API requests + key: api_requests + meter: + key: api_requests_total + capture: + - variable: FEATURE_ID + jq: ".id" + {% endkonnect_api_request %} + diff --git a/app/_includes/prereqs/metering-and-billing-plan-subscription.md b/app/_includes/prereqs/metering-and-billing-plan-subscription.md new file mode 100644 index 00000000000..c57ff375549 --- /dev/null +++ b/app/_includes/prereqs/metering-and-billing-plan-subscription.md @@ -0,0 +1,112 @@ +Create the entities you'll apply tax codes to in this guide. + +1. Create a meter: + + + {% konnect_api_request %} + url: /v3/openmeter/meters + method: POST + status_code: 201 + body: + name: API requests total + key: api_requests_total + event_type: request + aggregation: COUNT + {% endkonnect_api_request %} + + +1. Create a feature: + + + {% konnect_api_request %} + url: /v3/openmeter/features + method: POST + status_code: 201 + body: + name: API requests + key: api_requests + meter: + key: api_requests_total + capture: + - variable: FEATURE_ID + jq: ".id" + {% endkonnect_api_request %} + + +1. Create a plan with a rate card: + + + {% konnect_api_request %} + url: /v3/openmeter/plans + method: POST + status_code: 201 + body: + name: Example Plan + key: example_plan + currency: USD + billing_cadence: P1M + phases: + - name: default + key: default + rate_cards: + - name: API requests + key: api_requests + feature: + id: $FEATURE_ID + price: + type: unit + amount: "1" + entitlement: + type: boolean + capture: + - variable: PLAN_ID + jq: ".id" + {% endkonnect_api_request %} + + +1. Publish the plan: + + + {% konnect_api_request %} + url: /v3/openmeter/plans/$PLAN_ID/publish + method: POST + status_code: 200 + {% endkonnect_api_request %} + + +1. Create a customer: + + + {% konnect_api_request %} + url: /v3/openmeter/customers + method: POST + status_code: 201 + body: + name: Acme Inc + key: acme-inc + usage_attribution: + subject_keys: + - acme-inc + capture: + - variable: CUSTOMER_ID + jq: ".id" + {% endkonnect_api_request %} + + +1. Start a subscription: + + + {% konnect_api_request %} + url: /v3/openmeter/subscriptions + method: POST + status_code: 201 + body: + customer: + id: $CUSTOMER_ID + plan: + key: example_plan + capture: + - variable: SUBSCRIPTION_ID + jq: ".id" + {% endkonnect_api_request %} + From b380825b64e54209839d8d6b65cee0082c36d57b Mon Sep 17 00:00:00 2001 From: lena-larionova Date: Wed, 5 Aug 2026 15:26:19 -0700 Subject: [PATCH 3/4] add UI instructions to references instead --- app/metering-and-billing/customer.md | 22 ++--- app/metering-and-billing/product-catalog.md | 101 +++++++++++++++++++ app/metering-and-billing/subscriptions.md | 41 +++++++- app/metering-and-billing/tax-codes.md | 102 +++++++++++++++++++- 4 files changed, 249 insertions(+), 17 deletions(-) diff --git a/app/metering-and-billing/customer.md b/app/metering-and-billing/customer.md index 2a3b8a1f331..95cf9252c61 100644 --- a/app/metering-and-billing/customer.md +++ b/app/metering-and-billing/customer.md @@ -140,29 +140,27 @@ To create a customer in {{site.konnect_short_name}}, do the following: {% endnavtab %} {% navtab "Subject" %} -{:.warning} -> **Important:** During the billing beta, customers are limited to **one subject**. Support for multiple subjects will be available in the future. - -Subjects are created when you create the customer. To create a customer associated with a subject, send a `POST` request to the `/openmeter/customers` endpoint: +Subjects are created when you create the customer. +To create a customer associated with a subject: {% konnect_api_request %} url: /v3/openmeter/customers -status_code: 201 method: POST +status_code: 201 body: - name: "ACME Inc." - key: "019ae40f-4258-7f15-9491-842f42a7d6ac" - usageAttribution: - subjectKeys: - - "YOUR-SUBJECT-KEY" + name: ACME Inc. + key: acme-inc + usage_attribution: + subject_keys: + - YOUR-SUBJECT-KEY {% endkonnect_api_request %} -Replace `$KONNECT_TOKEN` with your [{{site.konnect_short_name}} personal or system access token](/konnect-api/#system-accounts-and-access-tokens) and `YOUR-SUBJECT-KEY` with the subject key from events that are associated with the customer. +Replace `YOUR-SUBJECT-KEY` with the subject key from events that you want to attribute to this customer. {:.info} -> {{site.konnect_short_name}} {{site.metering_and_billing}} will also automatically create a subject for you when you ingest an usage event for a new subject. +> **Note:** {{site.metering_and_billing}} also automatically creates a subject when you ingest a usage event for a new subject. {% endnavtab %} {% endnavtabs %} diff --git a/app/metering-and-billing/product-catalog.md b/app/metering-and-billing/product-catalog.md index c4ae8bb8699..f2369052787 100644 --- a/app/metering-and-billing/product-catalog.md +++ b/app/metering-and-billing/product-catalog.md @@ -190,6 +190,44 @@ rows: description: "The token type (for example, `input`, `output`, `cache_read`, `reasoning`). Static sets a fixed value, dynamic reads from a meter group-by dimension." {% endtable %} +### Create a feature + +To create a feature in {{site.konnect_short_name}}, do the following: + +{% navtabs "create-feature" %} +{% navtab "UI" %} + +1. In the {{site.konnect_short_name}} sidebar, click **{{site.metering_and_billing}}**. +1. In the {{site.metering_and_billing}} sidebar, click **Metering**. +1. Click the **Features** tab. +1. Click **Create Feature**. +1. Fill in the feature name and key. +1. Optionally, select a meter to associate with the feature. +1. Click **Save**. + +{% endnavtab %} +{% navtab "API" %} + + +{% konnect_api_request %} +url: /v3/openmeter/features +method: POST +status_code: 201 +body: + name: API Requests + key: api_requests + meter: + key: YOUR_METER_KEY +{% endkonnect_api_request %} + + +Replace `YOUR_METER_KEY` with the key of the meter you want to associate with the feature. + +For a complete tutorial, see [Meter and bill {{site.base_gateway}} API requests](/metering-and-billing/get-started/). + +{% endnavtab %} +{% endnavtabs %} + ### Feature configuration Features have a system-generated ID and a user-defined key. The key should be an easy-to-understand string that can be used to reference the feature in your codebase, `gpt_4_tokens` for example. @@ -228,6 +266,69 @@ Plans can take different forms, for example: * 10 GB storage included * SAML or SSO support +### Create a plan + +To create a plan in {{site.konnect_short_name}}, do the following: + +{% navtabs "create-plan" %} +{% navtab "UI" %} + +1. In the {{site.konnect_short_name}} sidebar, click **{{site.metering_and_billing}}**. +1. In the {{site.metering_and_billing}} sidebar, click **Catalog**. +1. Click **Create Plan**. +1. Fill in the plan name and key. +1. Set the currency and billing cadence. +1. Click **Add Rate Card** and select the feature you want to price. +1. Configure the pricing model and set your price per unit. +1. Save the rate card. +1. Click **Publish Plan** to make it available for subscriptions. + +{% endnavtab %} +{% navtab "API" %} + + +{% konnect_api_request %} +url: /v3/openmeter/plans +method: POST +status_code: 201 +body: + name: Example Plan + key: example_plan + currency: USD + billing_cadence: P1M + phases: + - name: default + key: default + rate_cards: + - name: API Requests + key: api_requests + feature: + id: YOUR_FEATURE_ID + price: + type: unit + amount: "1" + entitlement: + type: boolean +{% endkonnect_api_request %} + + +Then publish the plan to make it available for subscriptions: + + +{% konnect_api_request %} +url: /v3/openmeter/plans/{planId}/publish +method: POST +status_code: 200 +{% endkonnect_api_request %} + + +Replace `YOUR_FEATURE_ID` with the `id` of the feature you want to include, and `{planId}` with the `id` of the plan you created. + +For a complete tutorial, see [Meter and bill {{site.base_gateway}} API requests](/metering-and-billing/get-started/). + +{% endnavtab %} +{% endnavtabs %} + ### Rate cards Plans are built from rate cards, which determine which features a plan can access, the price, and how much of a feature they can use (called entitlements). Rate Cards define the configuration of features that subscribers will be entitled to and charged for. diff --git a/app/metering-and-billing/subscriptions.md b/app/metering-and-billing/subscriptions.md index cc7f6338a4f..265bd20a163 100644 --- a/app/metering-and-billing/subscriptions.md +++ b/app/metering-and-billing/subscriptions.md @@ -40,10 +40,47 @@ Subscriptions follow a billing cycle determined by their related [rate card](/me * The subscription start date, either the creation date or a specified future date. * The first day of the month, with usage prorated for the partial initial period. -To add a subscription to a customer, navigate to **{{site.metering_and_billing}}** > **Billing**, click your customer, and then click the **Subscriptions** tab in the {{site.konnect_short_name}} UI. - Active customer subscriptions can be enhanced with [add-ons](/metering-and-billing/add-ons/), which allow you to make changes to a customer's entitlements without changing the plan directly. +## Start a subscription + +To subscribe a customer to a plan in {{site.konnect_short_name}}, do the following: + +{% navtabs "start-subscription" %} +{% navtab "UI" %} + +1. In the {{site.konnect_short_name}} sidebar, click **{{site.metering_and_billing}}**. +1. In the {{site.metering_and_billing}} sidebar, click **Billing**. +1. Click your customer. +1. Click the **Subscription** tab. +1. Click **Create Subscription**. +1. Select the plan you want to assign to the customer. +1. Click **Next**. +1. Review the subscription details and click **Activate**. + +{% endnavtab %} +{% navtab "API" %} + + +{% konnect_api_request %} +url: /v3/openmeter/subscriptions +method: POST +status_code: 201 +body: + customer: + id: YOUR_CUSTOMER_ID + plan: + key: YOUR_PLAN_KEY +{% endkonnect_api_request %} + + +Replace `YOUR_CUSTOMER_ID` with the `id` of the customer and `YOUR_PLAN_KEY` with the `key` of the plan you want to assign. + +For a complete tutorial, see [Meter and bill {{site.base_gateway}} API requests](/metering-and-billing/get-started/). + +{% endnavtab %} +{% endnavtabs %} + ## Change plans Changing a plan switches a customer to a completely different plan. This is equivalent to canceling the current subscription and starting a new one on the new plan, but without any interruption in service. diff --git a/app/metering-and-billing/tax-codes.md b/app/metering-and-billing/tax-codes.md index 68f3a701bf7..773efa038a6 100644 --- a/app/metering-and-billing/tax-codes.md +++ b/app/metering-and-billing/tax-codes.md @@ -95,10 +95,106 @@ rows: {% endtable %} -To view your default and user-created tax codes, navigate to **Metering & Billing** > **Settings** and click the **Tax Codes** tab. +## Manage tax codes -To apply tax codes other than the default, navigate to the rate card on any plan, add-on, or customer subscription, and expand the advanced settings for the pricing model. -For a complete tutorial, see [Create and apply {{site.metering_and_billing}} tax codes](/how-to/configure-metering-and-billing-tax-codes/). +### Review default tax codes + +{% navtabs "review-tax-codes" %} +{% navtab "UI" %} + +1. In the {{site.konnect_short_name}} sidebar, click **{{site.metering_and_billing}}**. +1. In the {{site.metering_and_billing}} sidebar, click **Settings**. +1. Click the **Tax Codes** tab to view system-managed and user-created tax codes and the current organization defaults. + +{% endnavtab %} +{% navtab "API" %} + + +{% konnect_api_request %} +url: /v3/openmeter/tax-codes +method: GET +status_code: 200 +{% endkonnect_api_request %} + + +{% endnavtab %} +{% endnavtabs %} + +### Create a tax code + +If none of the system-managed codes match your product category, you can create a custom tax code. +For Stripe, the `app_mappings` value must follow the `txcd_XXXXXXXX` format. +You can browse available values in the [Stripe Tax Code reference](https://docs.stripe.com/tax/tax-codes). + +{% navtabs "create-tax-code" %} +{% navtab "UI" %} + +1. In the {{site.konnect_short_name}} sidebar, click **{{site.metering_and_billing}}**. +1. In the {{site.metering_and_billing}} sidebar, click **Settings**. +1. Click the **Tax Codes** tab. +1. Click **Create Tax Code**. +1. Fill in the name, key, and optional description. +1. Add an app mapping for your payment provider (for example, a Stripe tax code ID). +1. Click **Save**. + +{% endnavtab %} +{% navtab "API" %} + + +{% konnect_api_request %} +url: /v3/openmeter/tax-codes +method: POST +status_code: 201 +body: + name: Software as a Service + key: saas + description: Tax code for SaaS products + app_mappings: + - app_type: stripe + tax_code: txcd_10000000 +{% endkonnect_api_request %} + + +{% endnavtab %} +{% endnavtabs %} + +### Set organization defaults + +{% navtabs "set-tax-code-default" %} +{% navtab "UI" %} + +1. In the {{site.konnect_short_name}} sidebar, click **{{site.metering_and_billing}}**. +1. In the {{site.metering_and_billing}} sidebar, click **Settings**. +1. Click the **Tax Codes** tab. +1. Find the tax code you want to set as default and click the **...** menu. +1. Select **Set as invoicing default** or **Set as credit grant default**. + +{% endnavtab %} +{% navtab "API" %} + + +{% konnect_api_request %} +url: /v3/openmeter/defaults/tax-codes +method: PUT +status_code: 200 +body: + invoicing_tax_code: + id: YOUR_TAX_CODE_ID +{% endkonnect_api_request %} + + +Replace `YOUR_TAX_CODE_ID` with the `id` of the tax code you want to set as default. +Use `credit_grant_tax_code` instead of `invoicing_tax_code` to set the credit grant default. + +{:.info} +> **Note:** Only one tax code can be set as the default per category at a time. +> You can't delete a default tax code. +> To delete it, first set a different code as the default, then delete the original. + +{% endnavtab %} +{% endnavtabs %} + +For a complete tutorial including applying tax codes to rate cards, see [Create and apply {{site.metering_and_billing}} tax codes](/how-to/configure-metering-and-billing-tax-codes/). ## Fallback chain From 148e438859209209b7c641f99f413a6e2c692616 Mon Sep 17 00:00:00 2001 From: lena-larionova Date: Thu, 6 Aug 2026 16:55:45 -0700 Subject: [PATCH 4/4] fix config --- app/_how-tos/metering-and-billing/get-started.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/app/_how-tos/metering-and-billing/get-started.md b/app/_how-tos/metering-and-billing/get-started.md index 70633a17609..1e596f70382 100644 --- a/app/_how-tos/metering-and-billing/get-started.md +++ b/app/_how-tos/metering-and-billing/get-started.md @@ -167,14 +167,15 @@ Create a meter to count API requests: url: /v3/openmeter/meters method: POST body: - name: Total API requests + name: API requests key: api_requests_total - description: API Requests - event_type: request + description: Number of API requests + event_type: kong.api_request aggregation: count dimensions: - method: $.method - route: $.route + request_method: $.request_method + route_name: $.route_name + service_name: $.service_name {% endkonnect_api_request %}