feat(m&b): Convert UI how-tos to API

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:
+
+<!--vale off-->
+{% konnect_api_request %}
+url: /v3/openmeter/tax-codes
+method: GET
+status_code: 200
+{% endkonnect_api_request %}
+<!--vale on-->
+
+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:
+
+<!--vale off-->
+{% 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 %}
+<!--vale on-->
+
+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).
+
+<!--vale off-->
+{% 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 %}
+<!--vale on-->
+
+To set the new code as the invoicing default:
+
+<!--vale off-->
+{% 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 %}
+<!--vale on-->
 
 {:.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:
+
+<!--vale off-->
+{% 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 %}
+<!--vale on-->
 
 ### 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.

app/_how-tos/metering-and-billing/get-started-with-metering-and-billing.md → app/_how-tos/metering-and-billing/get-started-with-ai-agent-metering.md

@@ -76,13 +76,22 @@ In this guide, you'll:
 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**.
+<!--vale off-->
+{% 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 %}
+<!--vale on-->
 
-The template creates a meter with the following configuration:
+This creates a meter with the following configuration:
 
 <!--vale off-->
 {% table %}
@@ -109,12 +118,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 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**.
+<!--vale off-->
+{% 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 %}
+<!--vale on-->
 
 ## Create a plan and rate card
 
@@ -125,48 +143,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 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**.
+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:
+
+<!--vale off-->
+{% 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 %}
+<!--vale on-->
+
+{:.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:
+
+<!--vale off-->
+{% konnect_api_request %}
+url: /v3/openmeter/plans/$PLAN_ID/publish
+method: POST
+status_code: 200
+{% endkonnect_api_request %}
+<!--vale on-->
 
 ## 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**.
+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.
+
+<!--vale off-->
+{% 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 %}
+<!--vale on-->
+
+Then start a subscription to the Premium Plan:
+
+<!--vale off-->
+{% konnect_api_request %}
+url: /v3/openmeter/subscriptions
+method: POST
+status_code: 201
+body:
+  customer:
+    id: $CUSTOMER_ID
+  plan:
+    key: premium_plan
+{% endkonnect_api_request %}
+<!--vale on-->
 
 ## Validate
 
@@ -253,15 +314,19 @@ body:
 {% endcapture %}
 {{ run3 | indent: 3 }}
 
-Now check the invoice:
+Now check the usage charges:
+
+<!--vale off-->
+{% konnect_api_request %}
+url: /v3/openmeter/customers/$CUSTOMER_ID/charges?expand[]=real_time_usage
+method: GET
+status_code: 200
+{% endkonnect_api_request %}
+<!--vale on-->
 
-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 `agent-runs` with a `real_time_usage` quantity of `3`, reflecting three agent runs (two for `summarizer` and one for `translator`).
 
-You'll see `agent-runs` listed in Lines with a 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/).