diff --git a/app/_how-tos/ai-gateway/meter-llm-traffic.md b/app/_how-tos/ai-gateway/meter-llm-traffic.md index 9bd2cc7e13..5ea2649951 100644 --- a/app/_how-tos/ai-gateway/meter-llm-traffic.md +++ b/app/_how-tos/ai-gateway/meter-llm-traffic.md @@ -49,8 +49,8 @@ related_resources: url: /metering-and-billing/metering/ - text: Customers and usage attribution url: /metering-and-billing/customer/ - - text: Billing, invoicing, and subscriptions - url: /metering-and-billing/billing-invoicing-subscriptions/ + - 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: Get started with {{site.metering_and_billing}} generic meters @@ -218,6 +218,9 @@ body: This will generate AI LLM token usage that will be captured by {{site.metering_and_billing}}. +{:.info} +> **Entitlement enforcement:** The {{site.ai_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. + 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. 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 index b2ed05ea1c..d5a721a634 100644 --- a/app/_how-tos/gateway/get-started-with-metering-and-billing.md +++ b/app/_how-tos/gateway/get-started-with-metering-and-billing.md @@ -53,8 +53,8 @@ related_resources: url: /metering-and-billing/metering/ - text: Customers and usage attribution url: /metering-and-billing/customer/ - - text: Billing, invoicing, and subscriptions - url: /metering-and-billing/billing-invoicing-subscriptions/ + - 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 @@ -245,4 +245,7 @@ This will generate six requests. Now, check the invoice that was created in {{si 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**. \ No newline at end of file +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/gateway/meter-api-requests-by-consumer.md b/app/_how-tos/gateway/meter-api-requests-by-consumer.md index df94657b14..59a334e850 100644 --- a/app/_how-tos/gateway/meter-api-requests-by-consumer.md +++ b/app/_how-tos/gateway/meter-api-requests-by-consumer.md @@ -70,8 +70,8 @@ related_resources: url: /metering-and-billing/metering/ - text: Customers and usage attribution url: /metering-and-billing/customer/ - - text: Billing, invoicing, and subscriptions - url: /metering-and-billing/billing-invoicing-subscriptions/ + - text: Billing and invoicing + url: /metering-and-billing/billing-invoicing/ - text: Get started with {{site.metering_and_billing}} url: /metering-and-billing/get-started/ - text: Meter and bill active users @@ -173,4 +173,4 @@ You'll see three events listed, each with `subject: alice`, one for each request You'll also see an error message like `no customer found for event subject: consumer` associated with the event. This is expected since we're only tracking API usage. -If you want to meter and bill Consumer's usage, see [Metering](/metering-and-billing/metering/), [Customers and usage attribution](/metering-and-billing/customer/), and [Billing, invoicing, and subscriptions](/metering-and-billing/billing-invoicing-subscriptions/). +If you want to meter and bill Consumers' usage, see [Metering](/metering-and-billing/metering/), [Customers and usage attribution](/metering-and-billing/customer/), and [Billing and invoicing](/metering-and-billing/billing-invoicing/). 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 index 89d198f37d..bdf30a41b2 100644 --- 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 @@ -44,8 +44,8 @@ related_resources: url: /metering-and-billing/metering/ - text: Customers and usage attribution url: /metering-and-billing/customer/ - - text: Billing, invoicing, and subscriptions - url: /metering-and-billing/billing-invoicing-subscriptions/ + - 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 @@ -151,7 +151,7 @@ In this section, you'll create an Premium Plan plan that charges customers $1 pe ## 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/billing-invoicing-subscriptions/#subscriptions) them to the Premium Plan plan. +[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**. 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 c7fbbadcd4..5298d6a68e 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 @@ -43,8 +43,8 @@ related_resources: url: /metering-and-billing/metering/ - text: Customers and usage attribution url: /metering-and-billing/customer/ - - text: Billing, invoicing, and subscriptions - url: /metering-and-billing/billing-invoicing-subscriptions/ + - 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 @@ -133,7 +133,7 @@ In this section, you'll create a Per-Seat plan that charges customers $1 per act ## 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/billing-invoicing-subscriptions/#subscriptions) them to the Per-Seat plan. +[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**. diff --git a/app/_indices/metering-and-billing.yaml b/app/_indices/metering-and-billing.yaml index bd964c3f23..9577a356bb 100644 --- a/app/_indices/metering-and-billing.yaml +++ b/app/_indices/metering-and-billing.yaml @@ -8,8 +8,9 @@ sections: - path: /metering-and-billing/metering/ - path: /metering-and-billing/product-catalog/ - path: /metering-and-billing/customer/ - - path: /metering-and-billing/billing-invoicing-subscriptions/ + - path: /metering-and-billing/billing-invoicing/ - path: /metering-and-billing/events/ + - path: /metering-and-billing/notifications/ - title: Usage metering items: - title: API gateway metering @@ -52,13 +53,13 @@ sections: url: /metering-and-billing/customer/ - title: Subscriptions description: Subscriptions are a collection of active rate cards that can be assigned to customers. - url: /metering-and-billing/billing-invoicing-subscriptions/#subscriptions + url: /metering-and-billing/subscriptions/ - title: Billing profiles description: Billing profiles handle invoicing, payment, and tax settings for a customer. - url: /metering-and-billing/billing-invoicing-subscriptions/#billing-profiles + url: /metering-and-billing/billing-invoicing/#billing-profiles - title: Invoicing description: Learn how to set up invoicing in {{site.konnect_short_name}} {{site.metering_and_billing}}. - url: /metering-and-billing/billing-invoicing-subscriptions/#invoicing + url: /metering-and-billing/billing-invoicing/#invoicing - path: /metering-and-billing/stripe-integration/ - title: How tos items: diff --git a/app/_landing_pages/metering-and-billing.yaml b/app/_landing_pages/metering-and-billing.yaml index 7ca67b98c5..fcb9c5ac2a 100644 --- a/app/_landing_pages/metering-and-billing.yaml +++ b/app/_landing_pages/metering-and-billing.yaml @@ -201,7 +201,7 @@ rows: icon: /assets/icons/document.svg cta: text: Learn more - url: /metering-and-billing/billing-invoicing-subscriptions/#subscriptions + url: /metering-and-billing/subscriptions/ - blocks: - type: card config: @@ -211,7 +211,7 @@ rows: icon: /assets/icons/organization.svg cta: text: Learn more - url: /metering-and-billing/billing-invoicing-subscriptions/#billing-profiles + url: /metering-and-billing/billing-invoicing/#billing-profiles - blocks: - type: card config: @@ -221,7 +221,17 @@ rows: icon: /assets/icons/money.svg cta: text: Learn more - url: /metering-and-billing/billing-invoicing-subscriptions/#invoicing + url: /metering-and-billing/billing-invoicing/#invoicing + - blocks: + - type: card + config: + title: Notifications + description: | + Configure webhook alerts for usage thresholds and billing events. Use notifications to enforce entitlement limits in your infrastructure. + icon: /assets/icons/event.svg + cta: + text: Learn more + url: /metering-and-billing/notifications/ - header: type: h2 diff --git a/app/_redirects b/app/_redirects index 470f770368..d0593289bb 100644 --- a/app/_redirects +++ b/app/_redirects @@ -31,6 +31,7 @@ /mesh/use-kuma/ /mesh/interact-with-control-plane/ /mesh/configure-transparent-proxying/ /mesh/transparent-proxying/ /mesh/upgrade-notes/ /mesh/version-specific-upgrade-notes/ +/metering-and-billing/billing-invoicing-subscriptions/ /metering-and-billing/billing-invoicing/ # API spec links (delete when fixed) /gateway/latest/plan-and-deploy/security/secrets-management/getting-started /gateway/entities/vault/ diff --git a/app/metering-and-billing/billing-invoicing-subscriptions.md b/app/metering-and-billing/billing-invoicing.md similarity index 86% rename from app/metering-and-billing/billing-invoicing-subscriptions.md rename to app/metering-and-billing/billing-invoicing.md index 4d4a79f0ee..6dc489f88f 100644 --- a/app/metering-and-billing/billing-invoicing-subscriptions.md +++ b/app/metering-and-billing/billing-invoicing.md @@ -1,7 +1,7 @@ --- -title: "Billing, invoicing, and subscriptions" +title: "Billing and invoicing" content_type: reference -description: "Learn how billing, invoicing, and subscriptions work in {{site.konnect_short_name}} {{site.metering_and_billing}}." +description: "Learn how billing and invoicing work in {{site.konnect_short_name}} {{site.metering_and_billing}}." layout: reference products: - metering-and-billing @@ -14,6 +14,8 @@ breadcrumbs: related_resources: - text: "{{site.konnect_short_name}} {{site.metering_and_billing}}" url: /metering-and-billing/ + - text: Subscriptions + url: /metering-and-billing/subscriptions/ - text: Integrate Stripe with {{site.metering_and_billing}} url: /metering-and-billing/stripe-integration/ faqs: @@ -279,38 +281,5 @@ The invoice can include two kinds of lines: Billing and subscriptions in {{site.metering_and_billing}} create relationships between customers and their [pricing model](/metering-and-billing/pricing-models/). This serves as the bridge between your customers, their usage data, and how that usage translates into billable amounts. -Subscriptions automate the billing lifecycle by: - -* **Tracking usage** through meters -* **Applying pricing logic** from plans or custom configurations -* **Generating invoices** based on billing cadences -* **Enforcing entitlements** to control feature access - -Subscriptions can be created from predefined plans or fully customized at creation time to accommodate unique customer requirements. This flexibility supports everything from self-serve sign-ups to enterprise contract negotiations. - -Subscriptions follow a billing cycle determined by their related [rate card](/metering-and-billing/product-catalog/#rate-cards), anchored to one of the following: -* 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. - -## Plan migration - -Plans in {{site.metering_and_billing}} are versioned. When you update a plan, existing subscriptions remain on their current version. This is known as "grandfathering". Customers keep their existing pricing until they're explicitly migrated. - -Migrating a subscription to a new plan version allows you to: - -* Apply new pricing to existing customers -* Transition customers to improved plan structures -* Deprecate old plan versions -* Standardize customers on current offerings - -Migrations follow the same timing rules as other subscription changes: - -* **Immediate**: Migration takes effect right away -* **Next billing cycle**: Migration occurs at the end of the current period - -Choose timing based on whether the migration is favorable (immediate) or potentially disruptive (next cycle) to the customer. +For information on subscriptions, including how to change plans, customize, cancel, and migrate subscriptions, see [Subscriptions](/metering-and-billing/subscriptions/). diff --git a/app/metering-and-billing/customer.md b/app/metering-and-billing/customer.md index 1c6803898e..7ac88d44f3 100644 --- a/app/metering-and-billing/customer.md +++ b/app/metering-and-billing/customer.md @@ -14,6 +14,8 @@ breadcrumbs: related_resources: - text: "{{site.konnect_short_name}} {{site.metering_and_billing}}" url: /metering-and-billing/ + - text: Subscriptions + url: /metering-and-billing/subscriptions/ - text: Integrate Stripe with {{site.metering_and_billing}} url: /metering-and-billing/stripe-integration/ faqs: diff --git a/app/metering-and-billing/entitlements.md b/app/metering-and-billing/entitlements.md index eaf9c110ef..49d55eb22b 100644 --- a/app/metering-and-billing/entitlements.md +++ b/app/metering-and-billing/entitlements.md @@ -17,6 +17,10 @@ related_resources: url: /metering-and-billing/ - text: "Rate cards" url: /metering-and-billing/product-catalog/#rate-cards + - text: Subscriptions + url: /metering-and-billing/subscriptions/ + - text: Notifications + url: /metering-and-billing/notifications/ --- @@ -132,4 +136,11 @@ url: /v3/openmeter/customers/{customerId}/entitlement-access status_code: 200 method: GET {% endkonnect_api_request %} - \ No newline at end of file + + +## Entitlement enforcement + +{{site.metering_and_billing}} tracks entitlement balances in real time, but does not automatically enforce limits at the {{site.base_gateway}} or {{site.ai_gateway}} level. + +{:.info} +> **{{site.base_gateway}} and {{site.ai_gateway}} automatic enforcement is not available yet.** Automatic entitlement enforcement via a {{site.base_gateway}} plugin is planned for a future release. Until then, use [{{site.metering_and_billing}} Notifications](/metering-and-billing/notifications/) to receive a webhook when a customer reaches their entitlement threshold, and enforce access restrictions manually in your own infrastructure (for example, by removing a Consumer from a Consumer Group or returning a `403` response from your application). \ No newline at end of file diff --git a/app/metering-and-billing/notifications.md b/app/metering-and-billing/notifications.md new file mode 100644 index 0000000000..1c13519904 --- /dev/null +++ b/app/metering-and-billing/notifications.md @@ -0,0 +1,204 @@ +--- +title: "Notifications" +content_type: reference +description: "Use {{site.metering_and_billing}} Notifications to receive webhook alerts when customers reach entitlement thresholds or billing events occur." +layout: reference +products: + - metering-and-billing +works_on: + - konnect +breadcrumbs: + - /metering-and-billing/ +related_resources: + - text: "{{site.konnect_short_name}} {{site.metering_and_billing}}" + url: /metering-and-billing/ + - text: Entitlements + url: /metering-and-billing/entitlements/ + - text: "Billing and invoicing" + url: /metering-and-billing/billing-invoicing/ +--- + +{{site.metering_and_billing}} Notifications let you configure automated webhook alerts that trigger when specific usage thresholds or billing events occur. Instead of polling for usage data, you define rules that trigger notification events to a channel of your choice when conditions are met. + +## Use cases + +The following table describes the use cases for notifications: + +{% table %} +columns: + - title: Use case + key: case + - title: Description + key: description +rows: + - case: Entitlement enforcement + description: | + Receive a webhook when a customer reaches a percentage of their entitlement allowance (for example, 80% or 100%) and take action in your system, such as restricting access or sending a warning to the customer. +

+ See [Enforcing entitlement limits](#enforcing-entitlement-limits) for details. + - case: Customer warnings + description: Notify customers before they reach their usage limits to avoid unexpected service interruptions or overage charges. + - case: Sales alerts + description: Alert your sales team when a customer approaches or exceeds their plan limits to trigger an upgrade conversation. + - case: Invoice events + description: Receive a webhook when an invoice is created, issued, or paid to trigger downstream processes such as ERP sync or custom delivery. +{% endtable %} + + +## How it works + +The {{site.metering_and_billing}} Notifications system is built around three entities: + +{% mermaid %} +flowchart LR + Rule["Rule
(when to trigger)"] + Channel["Channel
(where to send)"] + Event["Event
(the notification sent)"] + + Rule --> Event + Event --> Channel +{% endmermaid %} + +2. **Rule**: Defines the condition that triggers a notification. When the condition is met, {{site.metering_and_billing}} sends a notification event to all channels attached to the rule. +3. **Event**: The notification payload delivered to your channel when a rule triggers. Events include details about the customer, entitlement, and the threshold that was crossed. +1. **Channel**: Defines where to send notifications. Currently, {{site.metering_and_billing}} supports webhook channels. A single channel can be referenced by multiple rules. + +## Channels + +A channel defines a delivery destination for notification events. {{site.metering_and_billing}} supports webhook channels, which send an HTTP POST request with a JSON payload to a URL of your choice. + +Use webhook channels to: + +* Integrate with Slack incoming webhooks +* Trigger threshold-based email alerts via your email provider +* Call an internal API to cut off a customer's access +* Forward events to your data warehouse or alerting platform + +### Create a channel + +To create a webhook channel in {{site.konnect_short_name}}: + +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 **Notifications** tab. +1. Click **Create Channel**. +1. In the **Name** field, enter a name for the channel. +1. In the **URL** field, enter the webhook URL to deliver notifications to. +1. (Optional) Add custom HTTP headers if your endpoint requires authentication. +1. Click **Save**. + +### Verify webhook requests + +When exposing a webhook endpoint, make sure the sender is authenticated before you process the payload. {{site.metering_and_billing}} lets you add custom HTTP headers when you create the channel. A common pattern is to configure a shared secret in a custom header, for example `Authorization: Bearer ` or `X-Webhook-Secret: `, and validate that value in your webhook handler for every delivery. + +Reject requests with a missing or invalid authentication header by returning a `400` or `401` response, and only process the notification after the header value matches the secret you configured on the channel. +## Rules + +A rule defines the condition that triggers a notification. When the condition is met, {{site.metering_and_billing}} delivers a notification event to the channels specified in the rule. + +{{site.metering_and_billing}} supports the following rule types: + +{% table %} +columns: + - title: Rule type + key: type + - title: Description + key: description +rows: + - type: "[Entitlement balance threshold](#entitlement-balance-threshold-rules)" + description: Triggers when a customer's entitlement balance crosses a specified percentage or absolute threshold. + - type: Entitlement reset + description: Triggers when an entitlement is reset, either manually or automatically. + - type: Invoice created + description: Triggers when a new invoice is created. + - type: Invoice updated + description: Triggers when an invoice changes state. +{% endtable %} + +{:.info} +> Notifications for [gathering invoices](/metering-and-billing/billing-invoicing/) are not currently supported. + +### Entitlement balance threshold rules + +Use this rule type to trigger notifications when a customer's [metered entitlement](/metering-and-billing/entitlements/#metered-entitlements) usage reaches a threshold. This is the primary rule type for implementing entitlement enforcement and customer warnings. + +To create an entitlement balance threshold rule: + +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 **Notifications** tab. +1. Click **Create Rule**. +1. In the **Name** field, enter a name for the rule. +1. From the **Type** dropdown menu, select "Entitlement balance threshold". +1. From the **Channels** dropdown menu, select one or more channels to deliver the notification to. +1. (Optional) From the **Features** dropdown menu, select features to scope the rule to. +1. From the **Thresholds** settings, add one or more thresholds. Each threshold triggers a separate notification event. +1. Click **Save**. + +## Notification events + +When a rule condition is met, {{site.metering_and_billing}} delivers a notification event as an HTTP POST request to all channels attached to the rule. The event payload is a JSON object containing the following information: + +{% table %} +columns: + - title: Field + key: field + - title: Description + key: description +rows: + - field: "`id`" + description: Unique identifier for the notification event. + - field: "`type`" + description: "The rule type that triggered this event, for example `entitlements.balance.threshold`." + - field: "`rule`" + description: The rule configuration that triggered this event. + - field: "`subject`" + description: The customer subject that triggered this event. + - field: "`threshold`" + description: The specific threshold that was crossed. + - field: "`feature`" + description: The feature key associated with the entitlement. + - field: "`entitlement`" + description: The entitlement configuration, including type and allowance. + - field: "`value`" + description: The current usage value or balance at the time the event was triggered. + - field: "`timestamp`" + description: The time at which the threshold was crossed. +{% endtable %} + +Each notification event has a delivery state: + + +{% table %} +columns: + - title: State + key: state + - title: Description + key: description +rows: + - state: "`PENDING`" + description: The event was created but sending hasn't started. + - state: "`SENDING`" + description: The event is actively being transmitted to the channel. + - state: "`SUCCESS`" + description: The event was delivered successfully. + - state: "`FAILED`" + description: The event couldn't be delivered. +{% endtable %} + + +You can view past notification events in {{site.konnect_short_name}} by navigating to **{{site.metering_and_billing}}** > **Settings** > **Notifications** and clicking the name of the rule. + +## Enforcing entitlement limits + +{{site.metering_and_billing}} tracks entitlement balances and triggers notification events when thresholds are crossed, but it does not automatically block API traffic when a customer's entitlement is exhausted. + +To enforce entitlement limits today, configure a webhook notification rule and handle the incoming event in your own system: + +1. [Create a webhook channel](#create-a-channel) pointing to an endpoint you control. +1. [Create an entitlement balance threshold rule](#entitlement-balance-threshold-rules) with a threshold at 100% for the feature you want to enforce. +1. In your webhook handler, take action when the event is received. For example: + * Remove the Consumer from a {{site.base_gateway}} Consumer Group that has access to the API. + * Return a `403 Forbidden` response from your application layer. + * Update a feature flag in your system to disable access for the customer. +1. (Optional) Add a second threshold at 80% to send a warning to the customer before access is cut off. diff --git a/app/metering-and-billing/overview.md b/app/metering-and-billing/overview.md index cf003f6fbf..04f946b019 100644 --- a/app/metering-and-billing/overview.md +++ b/app/metering-and-billing/overview.md @@ -14,8 +14,10 @@ related_resources: url: /metering-and-billing/ - text: Metering url: /metering-and-billing/metering/ - - text: "Billing, invoicing, and subscriptions" - url: /metering-and-billing/billing-invoicing-subscriptions/ + - text: "Billing and invoicing" + url: /metering-and-billing/billing-invoicing/ + - text: "Subscriptions" + url: /metering-and-billing/subscriptions/ next_steps: - text: Get started with {{site.metering_and_billing}} @@ -81,13 +83,13 @@ rows: support: "{{site.metering_and_billing}}" - capability: "[**Product catalog** (prices, plans, discounts)](/metering-and-billing/product-catalog/)" support: "{{site.metering_and_billing}}" - - capability: "[**Subscription management** (start, cancel, billing periods)](/metering-and-billing/billing-invoicing-subscriptions/#subscriptions)" + - capability: "[**Subscription management** (start, cancel, billing periods)](/metering-and-billing/subscriptions/)" support: "{{site.metering_and_billing}}" - - capability: "[**Entitlement management** (feature access and usage limits)](/metering-and-billing/billing-invoicing-subscriptions/#subscriptions)" + - capability: "[**Entitlement management** (feature access and usage limits)](/metering-and-billing/entitlements/)" support: "{{site.metering_and_billing}}" - - capability: "[**Rating** (unit × price, discounts, etc.)](/metering-and-billing/billing-invoicing-subscriptions/#discounts-and-commitments)" + - capability: "[**Rating** (unit × price, discounts, etc.)](/metering-and-billing/billing-invoicing/#discounts-and-commitments)" support: "{{site.metering_and_billing}}" - - capability: "[**Invoice generation** (billing periods, lines)](/metering-and-billing/billing-invoicing-subscriptions/#invoicing)" + - capability: "[**Invoice generation** (billing periods, lines)](/metering-and-billing/billing-invoicing/#invoicing)" support: "{{site.metering_and_billing}}" - capability: "**Sales tax calculations** (based on geo and tax code)" support: | @@ -114,4 +116,4 @@ rows: {{site.konnect_short_name}} {{site.metering_and_billing}} doesn't handle sales tax, payment processing, or invoice delivery directly. Instead, it integrates with vendors that specialize in these areas so you can choose the best fit for your business. -Combining multiple vendors is common. A startup might pair {{site.metering_and_billing}} with Stripe Payments for credit card processing, while a telecommunications company might use Avalara for tax because their industry's tax law is more complex than what general-purpose tools support. You connect these vendors through [apps and integrations](/metering-and-billing/#integrations). [Billing profiles](/metering-and-billing/billing-invoicing-subscriptions/#billing-profiles) in {{site.metering_and_billing}} let you use different vendors for different segments of your customers. +Combining multiple vendors is common. A startup might pair {{site.metering_and_billing}} with Stripe Payments for credit card processing, while a telecommunications company might use Avalara for tax because their industry's tax law is more complex than what general-purpose tools support. You connect these vendors through [apps and integrations](/metering-and-billing/#integrations). [Billing profiles](/metering-and-billing/billing-invoicing/#billing-profiles) in {{site.metering_and_billing}} let you use different vendors for different segments of your customers. diff --git a/app/metering-and-billing/product-catalog.md b/app/metering-and-billing/product-catalog.md index 8e82781bf0..66bf4d3d15 100644 --- a/app/metering-and-billing/product-catalog.md +++ b/app/metering-and-billing/product-catalog.md @@ -14,6 +14,8 @@ breadcrumbs: related_resources: - text: "{{site.konnect_short_name}} {{site.metering_and_billing}}" url: /metering-and-billing/ + - text: Subscriptions + url: /metering-and-billing/subscriptions/ - text: "Subjects" url: /metering-and-billing/subjects/ - text: "Pricing models" @@ -311,6 +313,9 @@ Entitlements can help you implement various monetization strategies: Entitlements are available in three types: metered, static, and boolean. See the [Entitlements reference](/metering-and-billing/entitlements/) to learn more. +{:.info} +> **Entitlement enforcement:** {{site.base_gateway}} and the {{site.ai_gateway}} do 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. + #### Grants A grant is a record of usage allowance issued to a specific customer via a metered entitlement. Grants determine how much of a feature a customer is allowed to consume. A metered entitlement tracks a running balance. When usage is reported, it is deducted from the grants issued for that entitlement. @@ -361,4 +366,4 @@ Example for reverse trials with plan phases: ## Subscriptions -{{site.konnect_short_name}} {{site.metering_and_billing}} [subscriptions](/metering-and-billing/billing-invoicing-subscriptions/#subscriptions) link your [Customers](/metering-and-billing/customer/) to plans, and [meters](/metering-and-billing/metering/). +{{site.konnect_short_name}} {{site.metering_and_billing}} [subscriptions](/metering-and-billing/subscriptions/) link your [Customers](/metering-and-billing/customer/) to plans, and [meters](/metering-and-billing/metering/). diff --git a/app/metering-and-billing/stripe-integration.md b/app/metering-and-billing/stripe-integration.md index 0ce4cd35d3..8f6d57c570 100644 --- a/app/metering-and-billing/stripe-integration.md +++ b/app/metering-and-billing/stripe-integration.md @@ -32,7 +32,7 @@ You can integrate Stripe Invoicing with {{site.konnect_short_name}} {{site.meter * Enable automatic sales tax calculation via Stripe tax * Support multiple payment methods and [currencies](https://docs.stripe.com/currencies) including cryptocurrency -## Revenue Lifecycle +## Revenue lifecycle The following lists show which parts of the revenue lifecycle is managed by {{site.konnect_short_name}} {{site.metering_and_billing}}, Stripe Invoicing, Stripe Tax, and Stripe Payments: @@ -69,7 +69,7 @@ When you configure the Stripe app in {{site.metering_and_billing}}, {{site.konne You can use one or both methods by setting up one or more billing profiles. This is useful if you have different payment collection methods for different customers. For example, you can have a billing profile for self-service customers with automatic payment collection and a billing profile for enterprise customers with email invoicing. You can set the self-service billing profile as the default and link enterprise customers to the enterprise billing profile. This way your self-service customers are charged automatically and your enterprise clients will receive an email invoice. -When the Stripe app is installed and set as a [billing profile](/metering-and-billing/billing-invoicing-subscriptions/#billing-profiles), {{site.metering_and_billing}} will automatically synchronize invoices to Stripe Invoicing. {{site.metering_and_billing}} will create a Stripe Invoice for each {{site.metering_and_billing}} invoice and mark invoices as finalized to kick of the payment collection in Stripe. +When the Stripe app is installed and set as a [billing profile](/metering-and-billing/billing-invoicing/#billing-profiles), {{site.metering_and_billing}} will automatically synchronize invoices to Stripe Invoicing. {{site.metering_and_billing}} will create a Stripe Invoice for each {{site.metering_and_billing}} invoice and mark invoices as finalized to kick off the payment collection in Stripe. When a paid subscription is created, {{site.metering_and_billing}} will enforce that a customer linked with Stripe has either a default payment method or an email address depending on the collection method settings. diff --git a/app/metering-and-billing/subscriptions.md b/app/metering-and-billing/subscriptions.md new file mode 100644 index 0000000000..0b93a7f817 --- /dev/null +++ b/app/metering-and-billing/subscriptions.md @@ -0,0 +1,105 @@ +--- +title: "Subscriptions" +content_type: reference +description: "Learn how subscriptions work in {{site.konnect_short_name}} {{site.metering_and_billing}} and how to change, edit, cancel, and migrate them." +layout: reference +products: + - metering-and-billing +tools: + - konnect-api +works_on: + - konnect +breadcrumbs: + - /metering-and-billing/ +related_resources: + - text: "Billing and invoicing" + url: /metering-and-billing/billing-invoicing/ + - text: Product Catalog + url: /metering-and-billing/product-catalog/ + - text: Entitlements + url: /metering-and-billing/entitlements/ + - text: "{{site.konnect_short_name}} {{site.metering_and_billing}}" + url: /metering-and-billing/ +--- + +Subscriptions in {{site.metering_and_billing}} create relationships between [customers](/metering-and-billing/customer/) and their [pricing model](/metering-and-billing/pricing-models/).. They are the bridge between your customers, their usage data, and how that usage translates into billable amounts. + +Subscriptions automate the billing lifecycle by: + +* **Tracking usage** through meters +* **Applying pricing logic** from plans or custom configurations +* **Generating invoices** based on billing cadences +* **Enforcing entitlements** to control feature access + +Subscriptions can be created from predefined plans or fully customized at creation time to accommodate unique customer requirements. This flexibility supports everything from self-serve sign-ups to enterprise contract negotiations. + +Subscriptions follow a billing cycle determined by their related [rate card](/metering-and-billing/product-catalog/#rate-cards), anchored to one of the following: + +* 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. + +## 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. + +To change a customer's 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 the customer whose subscription you want to change. +1. Click the **Subscription** tab. +1. Click **Manage**. +1. Select the new plan. +1. Click **Next**. +1. Select when the plan change should be effective **At the end of the billing period** or **Immediately**. + * **At the end of the billing period**: Select for downgrades to avoid disrupting the customer's current service period. + * **Immediately**: Select for upgrades so the customer gets access to the new plan right away. + +1. Click **Save Changes**. + + + +## Cancel a subscription + +Canceling a subscription ends it and stops future invoices from being generated. You can cancel immediately or at the end of the current billing period. + +To cancel a subscription: + +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 customer whose subscription you want to cancel. +1. Click the **Subscriptions** tab. +1. Click **Cancel Subscription**. +1. Select when the plan change should be effective **At the end of the billing period** or **Immediately**. + * **At the end of the billing period**: Select for downgrades to avoid disrupting the customer's current service period. + * **Immediately**: Select for upgrades so the customer gets access to the new plan right away. +1. Click **Save Changes**. + +## Plan migration + +Plans in {{site.metering_and_billing}} are versioned. When you publish a new version of a plan, existing subscriptions remain on the previous version until explicitly migrated. This is known as grandfathering, customers keep their existing pricing until you choose to migrate them. + +Migrating a subscription to a new plan version allows you to: + +* Apply new pricing to existing customers +* Transition customers to improved plan structures +* Deprecate old plan versions +* Standardize customers on current offerings + +You can migrate customers selectively, migrating enterprise customers first and rolling out changes to self-serve customers later, for example. + +To migrate a subscription to a new plan version: + +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 customer whose subscription you want to migrate. +1. Click the **Subscriptions** tab. +1. Click **Manage**. +1. Click **Migrate**. +1. Click **Next**. +1. Choose when the migration should be effective: **At the end of the billing period** or **Immediately**. +1. Click **Save**.