Skip to content

Commit 74ae1a1

Browse files
cloudjumpercatcloudjumpercat
committed
rework billing page
Signed-off-by: Diana <75819066+cloudjumpercat@users.noreply.github.com>
1 parent a832b6d commit 74ae1a1

File tree

4 files changed

+218
-133
lines changed

4 files changed

+218
-133
lines changed

‎app/_includes/konnect/metering-and-billing/tax.md‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
{{site.metering_and_billing}} automatically uses external services to calculate and add taxes to invoices. Currently, {{site.metering_and_billing}} supports [Stripe Tax](https://stripe.com/tax).
2+
3+
{{site.metering_and_billing}} supports the following tax settings:
4+
5+
* Inclusive: The listed price already includes tax. A 10% inclusive tax on a $500 item still results in a $500 invoice.
6+
* Exclusive: Tax is added on top of the listed price. A 10% exclusive tax on a $500 item raises the invoice total to $550.
7+
* Tax codes: Apply a tax code to a feature. Some payment providers, like Stripe, apply their own default [tax code](https://docs.stripe.com/tax/tax-codes). In those cases, you can leave {{site.metering_and_billing}}'s tax settings blank.
8+
9+
You can enable tax collection from a [Rate Card](/metering-and-billing/product-catalog/) or the [billing profile settings](https://cloud.konghq.com/metering-billing/billing-profiles).
10+
11+
In {{site.metering_and_billing}}, you can define the tax behavior on multiple levels, from lowest to highest precedence:
12+
13+
{% table %}
14+
columns:
15+
- title: Use Case
16+
key: use_case
17+
- title: Setting
18+
key: setting
19+
rows:
20+
- use_case: "Fallback to the tax behavior of the payment provider, like Stripe."
21+
setting: "[Payment provider](https://cloud.konghq.com/metering-billing/apps)"
22+
- use_case: "Define the default tax behavior, if any, for all customers."
23+
setting: "[Billing profile](https://cloud.konghq.com/metering-billing/billing-profiles)"
24+
- use_case: "Override the default tax behavior on a per Rate Card basis."
25+
setting: "[Plan Rate Card](/)"
26+
- use_case: "Override the default tax behavior on a per-subscription basis."
27+
setting: "[Subscription Rate Card](/)"
28+
- use_case: "Override the tax behavior per invoice line item."
29+
setting: "[Invoice](https://cloud.konghq.com/metering-billing/invoices)"
30+
{% endtable %}
31+
32+
We recommend setting the tax behavior on the payment provider level if you use Stripe for tax calculation. Tax behavior is optional at the billing profile, plan rate card, and subscription rate card levels.
33+
34+
When tax enforcement is enabled, {{site.metering_and_billing}} prevents you from starting a subscription if automatic tax calculation isn't supported. When enforcement is enabled, the following actions are blocked:
35+
36+
* Creating a paid subscription when tax cannot be calculated
37+
* Finalizing an invoice when tax cannot be calculated
38+
* Validation logic also varies by tax service. For example, with Stripe Tax, {{site.metering_and_billing}} uses Stripe's APIs to verify whether tax calculation is supported for the customer. In that case of Stripe, the customer must have a valid tax location.

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

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

‎app/metering-and-billing/billing-invoicing-subscriptions.md‎

Lines changed: 176 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,176 @@
1+
---
2+
title: "Billing, invoicing, and subscriptions"
3+
content_type: reference
4+
description: "Learn how billing, invoicing, and subscriptions work in {{site.konnect_short_name}} {{site.metering_and_billing}}."
5+
layout: reference
6+
products:
7+
- metering-and-billing
8+
tools:
9+
- konnect-api
10+
works_on:
11+
- konnect
12+
breadcrumbs:
13+
- /metering-and-billing/
14+
related_resources:
15+
- text: "{{site.konnect_short_name}} Metering and Billing"
16+
url: /metering-and-billing/
17+
---
18+
19+
## Billing profiles
20+
21+
Billing profiles contain the invoicing, payment, and tax settings for billing and controls invoice generation. An organization can have multiple billing profiles defined. This is useful when you have different billing needs for different customers. For example, you might want some customers to be billed via Stripe and others via bank transfer.
22+
23+
Each {{site.metering_and_billing}} instance has one default billing profile that all new customers will be assigned to unless otherwise specified. An exception to this is when modifying the default billing profile from Sandbox to a production app, customers with outstanding invoices are automatically retained on the Sandbox-based billing profile to prevent unintended charges from test data.
24+
25+
A billing profile is linked to a specific App. This association is established during the billing profile's creation and remains immutable. When transitioning to a new app, organizations must [migrate to a new billing profile](#customer-billing-profile-overrides).
26+
27+
Billing profiles can be managed from the [**Billing Profiles**](https://cloud.konghq.com/metering-billing/billing-profiles) tab in **Metering & Billing > Settings** in the {{site.konnect_short_name}} UI.
28+
29+
### Invoicing settings
30+
31+
The invoicing settings define the invoice creation process and lifecycle management parameters, including:
32+
33+
* Whether invoices are sent automatically (auto advance) for payment collection or if they require approval first
34+
* If intermediate invoices are allowed
35+
* How long to wait for late usage events
36+
* How long to wait before sending the invoice
37+
38+
You may want to disable auto advance for the following use cases:
39+
40+
* Initial billing configuration validation: Enables manual verification of charges prior to customer distribution
41+
* Emergency control mechanism: Provides immediate invoice control during system integration issues or event reporting anomalies
42+
* External system integration requirements: Accommodates scenarios requiring synchronization with external systems prior to invoice finalization
43+
44+
Strategic applications of auto advance with extended draft periods:
45+
46+
* Facilitates internal review processes by support and sales teams before customer distribution.
47+
* Enables quality assurance checks on high-value accounts.
48+
* Default tax behavior establishes the standard tax handling for invoice line items, unless overridden by subscription-specific Rate Card settings.
49+
50+
### Payment settings
51+
52+
Payment method determines the invoice settlement process. {{site.metering_and_billing}} currently supports two payment methods:
53+
54+
* **Charge automatically:** Processes payment immediately using the customer's stored payment card.
55+
* **Send invoice:** Issues an invoice to the customer for payment via their preferred method (credit card, bank transfer, or other supported payment options).
56+
57+
Invoice due after/Payment due after (period) specifies the duration allowed for invoice payment after finalization. This grace period applies to all payment methods, including credit card payments which may be declined. If payment is not received within this timeframe, the invoice status will transition to overdue.
58+
59+
### Customer billing profile overrides
60+
61+
Customer overrides allows you to assign a different billing profile to customers other than the default. By default customers are pinned to the default billing profile. This is useful when you have different billing needs for different customers. For example, you might want some customers to be billed via Stripe and others via bank transfer.
62+
63+
Customer overrides can be useful for the following use cases:
64+
* **Enterprise billing**: Set up one billing profile for SaaS customers and another for Enterprise customers (with send invoice for bank transfer selected).
65+
* **Migrating customers billing**: Create a new billing profile that you want to migrate customers to and then assign them to the new profile with a customer override.
66+
67+
Configure customer overrides by navigating to **Metering & Billing** > [**Billing**](https://cloud.konghq.com/metering-billing/customers), click a customer, then navigate to the **Billing Profile** section of the customer settings.
68+
69+
## Tax calculations
70+
71+
{% include_cached /konnect/metering-and-billing/tax.md %}
72+
73+
## Invoicing
74+
75+
Invoices are created when a subscription starts and are kept up-to-date with the subscription state. The subscription [Rate Card](/metering-and-billing/product-catalog/#rate-cards) governs the price and the invoicing frequency for the specified feature. For example, a subscription with a single in-advance flat fee billed monthly will generate one invoice per month.
76+
77+
{{site.metering_and_billing}} invoices follow a well-defined lifecycle that aligns directly with their associated subscription periods. Each invoice serves as an immutable record of billing information, which ensures complete data integrity and audit compliance throughout the billing process.
78+
79+
The invoice document maintains comprehensive and structured information that is essential for billing transparency. Invoices contain the following information:
80+
* The total amount of lines before discounts and taxes
81+
* The total amount of charges (minimum spend) before discounts and taxes
82+
* The total amount of discounts applied
83+
* The total amount of inclusive and exclusive taxes
84+
* The total amount of taxes
85+
* The total amount after taxes and discounts charged to the customer
86+
87+
To view invoices in {{site.konnect_short_name}}, navigate to **Metering & Billing** > **Billing** and click the **Invoices** tab.
88+
89+
### Invoice lifecycle
90+
91+
The following table describes the different states of the invoice lifecycle:
92+
93+
{% table %}
94+
columns:
95+
- title: State
96+
key: state
97+
- title: Possible transitions
98+
key: transitions
99+
- title: Description
100+
key: description
101+
rows:
102+
- state: Gathering
103+
transitions: N/A
104+
description: "Gathering the items to be invoiced. Note: for details please see Gathering Invoices, in this page only the other states will be discussed"
105+
- state: Draft
106+
transitions: "Issued, Deleted"
107+
description: "The invoice is created and in draft state. The invoice can only be updated in this state. In later states the invoice can only be voided."
108+
- state: Issued
109+
transitions: Payment Processing
110+
description: "The invoice is issued to the customer."
111+
- state: Payment Processing
112+
transitions: "Overdue, Unable to be collected, Paid, Void"
113+
description: "Payment is being processed."
114+
- state: Overdue
115+
transitions: "Paid, Void, Unable to be collected"
116+
description: "The invoice is overdue."
117+
- state: Unable to be collected
118+
transitions: "Paid, Void"
119+
description: "The invoice has been marked as unable to be collected."
120+
- state: Paid
121+
transitions: N/A
122+
description: "The invoice has been paid."
123+
- state: Void
124+
transitions: N/A
125+
description: "The invoice has been voided."
126+
- state: Deleted
127+
transitions: N/A
128+
description: "The invoice has been deleted and is no longer available."
129+
{% endtable %}
130+
131+
### Gathered invoices
132+
133+
To enable threshold billing scenarios, {{site.metering_and_billing}} creates gathering invoices with upcoming charges for the next billing cycle. These gathering invoices show current pending charges for the user's current billing period in real-time when fetched or viewed, providing visibility into accruing usage before the final invoice is issued.
134+
135+
Gathering invoices are automatically deleted when the last item for a subscription has been billed for.
136+
137+
Given an invoice is always single currency, if the customer was migrated between currencies they might have one gathering invoice per currency.
138+
139+
{:.warning}
140+
> **Important:** For systematic changes that need to persist across billing cycles, we recommend modifying the subscription directly rather than editing gathering invoices. This ensures consistent billing behavior aligned with the intended subscription terms.
141+
142+
{% include_cached /konnect/metering-and-billing/discounts.md %}
143+
144+
## Subscriptions
145+
146+
Billing and subscriptions in {{site.metering_and_billing}} create relationships between customers and their pricing model. This serves as the bridge between your customers, their usage data, and how that usage translates into billable amounts.
147+
148+
Subscriptions automate the billing lifecycle by:
149+
150+
* **Tracking usage** through meters
151+
* **Applying pricing logic** from plans or custom configurations
152+
* **Generating invoices** based on billing cadences
153+
* **Enforcing entitlements** to control feature access
154+
155+
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.
156+
157+
To add a subscription to a customer, navigate to **Metering & Billing** > **Billing**, click your customer, and then click the **Subscriptions** tab in the {{site.konnect_short_name}} UI.
158+
159+
## Plan migration
160+
161+
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.
162+
163+
Migrating a subscription to a new plan version allows you to:
164+
165+
* Apply new pricing to existing customers
166+
* Transition customers to improved plan structures
167+
* Deprecate old plan versions
168+
* Standardize customers on current offerings
169+
170+
Migrations follow the same timing rules as other subscription changes:
171+
172+
* **Immediate**: Migration takes effect right away
173+
* **Next billing cycle**: Migration occurs at the end of the current period
174+
175+
Choose timing based on whether the migration is favorable (immediate) or potentially disruptive (next cycle) to the customer.
176+

‎app/metering-and-billing/product-catalog.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -165,6 +165,10 @@ rows:
165165

166166
Besides the **Free** pricing model, other models require configuration that you can see from the {{site.konnect_short_name}} UI.
167167

168+
#### Tax calculations
169+
170+
{% include_cached /konnect/metering-and-billing/tax.md %}
171+
168172
#### Entitlements
169173

170174
Entitlements are used to control access to different features, they make it possible to implement complex pricing scenarios such as monthly quotas, prepaid billing, and per-customer pricing.

0 commit comments

Comments
 (0)