Merge pull request #460 from kinde-oss/Feat/Update-Billing-docs

Feat/metered charges and url changes for billing

Author: clairekinde11

src/content/docs/billing/billing-user-experience/add-billing-to-url-sdk.mdx

@@ -0,0 +1,92 @@
+---
+page_id: db047df7-d6b6-4d02-843f-dce6000bacbd
+title: Update code and URLs for billing
+sidebar:
+  order: 3
+relatedArticles:
+  - bd6757e3-81d5-48d6-89c8-dd4c222ac647
+  - 100f75f1-a0a4-459f-874f-da127f2d0615
+---
+
+This topic explains how to customize billing flows with Kinde, including URL parameters, direct auth URLs, and SDK usage in React.
+
+Examples are given in React, but can be adapted for most frameworks.
+
+## Edit the auth URL parameters directly
+
+Here’s a standard Kinde auth URL:
+
+```
+
+https://<your_kinde_subdomain>.kinde.com/oauth2/auth
+  ?response_type=code
+  &client_id=<your_kinde_client_id>
+  &redirect_uri=<your_app_redirect_url>
+  &scope=openid%20profile%20email
+  &state=abc
+
+```
+
+Add these parameters as needed:
+
+| Parameter | Description |
+| --- | --- |
+| `plan_interest` | Pre-selects a plan (skips plan selection) |
+| `pricing_table_key` | Displays a specific pricing table |
+| `is_create_org` | Triggers org sign-up flow |
+
+### Examples
+
+- Pre-select a plan:
+    
+    ```
+    ...&plan_interest=pro_monthly
+    ```
+    
+- Show specific pricing:
+    
+    ```
+    ...&pricing_table_key=spring_promo
+    ```
+    
+- Org sign-up:
+
+    ```
+    ...&is_create_org=true
+    ```
+
+## Integrate billing using the React SDK
+
+You can avoid manual URL construction by using our SDK components. Here's how.
+
+**User sign-up (default):**
+
+```jsx
+<RegisterLink>Sign up</RegisterLink>
+```
+
+**Org sign-up (B2B):**
+
+```jsx
+<RegisterLink isCreateOrg>Sign up your organization</RegisterLink>
+```
+
+**Pre-select a user plan:**
+
+```jsx
+<RegisterLink planInterest="pro_monthly">Sign up with Pro plan</RegisterLink>
+```
+
+**Show a specific pricing table:**
+
+```jsx
+<RegisterLink pricingTableKey="spring_promo">Spring Promo Sign up</RegisterLink>
+```
+
+**Combine for B2B + pricing table:**
+
+```jsx
+<RegisterLink isCreateOrg pricingTableKey="enterprise_2024">
+  Sign up your company
+</RegisterLink>
+```

src/content/docs/billing/billing-user-experience/plan-selection.mdx

@@ -119,3 +119,7 @@ You can configure Kinde to hide pricing tables in the sign up flow, but still sh
 1. Go to **Settings > Environment > Billing**.
 2. Switch off the **Show the pricing table when customers sign up** option. 
 3. Select **Save**. 
+
+## Add plan selector to registration URL
+
+Use your SDK or manually change URL params to incorporate billing. See [Add billing to URl or SDK](/billing/billing-user-experience/add-billing-to-url-sdk/)

src/content/docs/billing/get-started/setup-overview.mdx

@@ -16,14 +16,14 @@ Billing is big step for a business, so it’s a good idea to review the process
 ## Overview of billing setup
 
 1. [Set up billing roles and permissions (B2B)](/billing/get-started/add-billing-role/)
-2. [Set currency](/billing/get-started/default-billing-currency/) - you can’t change this once your first plan is published
-3. [Connect to Stripe](/billing/get-started/connect-to-stripe/)
+2. [Connect to Stripe and set billing policies](/billing/get-started/connect-to-stripe/) 
+3  [Set currency](/billing/get-started/default-billing-currency/) - you can’t change this once your first plan is published
 4. [Build plans](/billing/manage-plans/create-plans/)
 5. [Publish plans](/billing/get-started/publish-plans/)
 6. Enable subscription self-serve (optional)
     1. [Create a plan selector](/billing/billing-user-experience/plan-selection/)
     2. [Enable self-serve portal](/build/set-up-options/self-serve-portal-for-orgs/)
-7. Update your code
+7. [Update your code and registration URLs](/billing/billing-user-experience/add-billing-to-url-sdk/)
 8. Test the setup and get your first subscriber!
 
 ## ⚠️ Test in a non-production environment

src/content/docs/billing/manage-subscribers/add-metered-usage.mdx

@@ -0,0 +1,37 @@
+---
+page_id: 7060212e-5e8c-4188-acd3-e055e3474988
+title: Add metered usage for a customer via API
+sidebar:
+  order: 1
+relatedArticles:
+  - 7f59a705-ac5d-4b07-a44e-1421dcdeffe8
+---
+
+From time to time, you may need to manually add metered usage for an individual customer. You can do this via the Kinde API.
+
+Adding usage values requires two key pieces of information:
+
+- your customer's agreement ID
+- the feature code you want to record usage against
+
+## Get the agreement ID
+
+- [Via API](https://docs.kinde.com/kinde-apis/management/#tag/billing-agreements/get/api/v1/billing/agreements/). Include the `billing` expand parameter in your request to access the agreement ID.
+
+- Via the Kinde UI - Open the user or organization record in Kinde and select **Billing** in the menu. The customer agreement shows as part of the subscription details. 
+
+## Get the feature ID
+
+1. Open the plan the feature belongs to.
+2. Edit the feature (to view it) in the plan.
+3. Take note of the **Key**.
+
+## Submit usage data
+
+POST the usage to the [meter usage record API](https://docs.kinde.com/kinde-apis/management/#tag/billing-meter-usage/post/api/v1/billing/meter_usage/) including the feature code and agreement ID to record a usage value.
+
+<Aside>
+
+Usage gets assigned to your customer's current billing cycle. Any usage submitted after a billing cycle ends will be recorded against the next billing cycle.
+
+</Aside>

src/content/docs/billing/pricing/pricing-models.mdx

@@ -6,6 +6,7 @@ sidebar:
 relatedArticles:
   - fe9fea0c-274c-4d6b-9cc5-eccdbaad85b7
   - d980a089-d9c1-447b-930a-de0f2c00d3bf
+  - 7060212e-5e8c-4188-acd3-e055e3474988
 ---
 
 A pricing model refers to the structured approach businesses use to charge customers for products and services, often based on factors like usage, feature access, or licensing. In Kinde, each feature you include in a plan has a pricing model attached. This topic describes some examples of pricing models you can apply in Kinde, when you might want to use them, and how to [set them up in your Kinde plans](/billing/manage-plans/create-plans/).
@@ -22,10 +23,16 @@ In Kinde, create a **Fixed charge** and call it something like `Subscription fee
 
 - Example - Basic plan 5.00, Team plan 20.00, Business plan 75.00.
 
-## Usage-based pricing
+## Usage-based (metered) pricing
 
 Where you charge customers for what they use. For example, monthly active users, data storage, transactions, etc. For each individual plan you can treat this as fully pay-as-you-go, or charge volume prices so the price goes down the more units are used. You can set limits for usage based pricing or leave as limitless. Limits can make plan upgrade more attractive. 
 
+<Aside>
+
+If you need to, you can [add metered amounts to individual customer plans via the Kinde API](/billing/manage-subscribers/add-metered-usage/). 
+
+</Aside>
+
 ### Usage pricing - per unit
 
 In Kinde, add a **New metered feature**, e.g. `Data storage`. Leave **Maximum units** blank for limitless, or set a limit. Select a **per unit** pricing model. Set a price for each unit. E.g.

src/data/sidebarData.ts

@@ -162,6 +162,11 @@ const sidebarData = [
         autogenerate: {directory: "billing/payment-management"},
         collapsed: false
       },
+      {
+        label: "Subscription management",
+        autogenerate: {directory: "billing/manage-subscribers"},
+        collapsed: false
+      },
       {
         label: "Pricing",
         autogenerate: {directory: "billing/pricing"},