Add Billing hooks and custom flows

docs/_partials/billing/add-new-payment-method.mdx

@@ -0,0 +1,82 @@
+The following example demonstrates how to create a billing page where a user can add a new payment method. It is split into two components:
+
+- **`<UserBillingPage />`**: Sets up the `<PaymentElementProvider />`, which specifies that the payment actions within its children are `for` the `user`.
+- **`<AddPaymentMethodForm />`**: Renders the payment form and handles the submission logic. It uses `usePaymentElement()` to get the `submit` function and `useUser()` to get the `user` object. When the form is submitted, it first creates a payment token and then attaches it to the user.
+
+<CodeBlockTabs options={["<UserBillingPage />", "<AddPaymentMethodForm />"]}>
+  ```tsx {{ filename: 'app/user/billing/page.tsx' }}
+  import { ClerkLoaded } from '@clerk/nextjs'
+  import { PaymentElementProvider } from '@clerk/nextjs/experimental'
+  import { AddPaymentMethodForm } from './AddPaymentMethodForm'
+
+  export default function Page() {
+    return (
+      <div>
+        <h1>Billing Settings</h1>
+
+        <ClerkLoaded>
+          <PaymentElementProvider for="user">
+            <AddPaymentMethodForm />
+          </PaymentElementProvider>
+        </ClerkLoaded>
+      </div>
+    )
+  }
+  ```
+
+  ```tsx {{ filename: 'app/user/billing/AddPaymentMethodForm.tsx' }}
+  'use client'
+  import { useUser } from '@clerk/nextjs'
+  import { usePaymentElement, PaymentElement } from '@clerk/nextjs/experimental'
+  import { useState } from 'react'
+
+  export function AddPaymentMethodForm() {
+    const { user } = useUser()
+    const { submit, isFormReady } = usePaymentElement()
+    const [isSubmitting, setIsSubmitting] = useState(false)
+    const [error, setError] = useState<string | null>(null)
+
+    const handleAddPaymentMethod = async (e: React.FormEvent) => {
+      e.preventDefault()
+      if (!isFormReady || !user) {
+        return
+      }
+
+      setError(null)
+      setIsSubmitting(true)
+
+      try {
+        // 1. Submit the form to the payment provider to get a payment token
+        const { data, error } = await submit()
+
+        // Usually a validation error from stripe that you can ignore.
+        if (error) {
+          setIsSubmitting(false)
+          return
+        }
+
+        // 2. Use the token to add the payment source to the user
+        await user.addPaymentSource(data)
+
+        // 3. Handle success (e.g., show a confirmation, clear the form)
+        alert('Payment method added successfully!')
+      } catch (err: any) {
+        setError(err.message || 'An unexpected error occurred.')
+      } finally {
+        setIsSubmitting(false)
+      }
+    }
+
+    return (
+      <form onSubmit={handleAddPaymentMethod}>
+        <h3>Add a new payment method</h3>
+        <PaymentElement />
+        <button type="submit" disabled={!isFormReady || isSubmitting}>
+          {isSubmitting ? 'Saving...' : 'Save Card'}
+        </button>
+        {error && <p style={{ color: 'red' }}>{error}</p>}
+      </form>
+    )
+  }
+  ```
+</CodeBlockTabs>

docs/_partials/billing/api-experimental-guide.mdx

@@ -0,0 +1,3 @@
+> [!WARNING]
+>
+> This guide is using experimental APIs and subject to change while Clerk Billing is under Beta. To mitigate potential disruptions, we recommend [pinning](https://docs.renovatebot.com/dependency-pinning/#what-is-dependency-pinning) your SDK and `clerk-js` package versions.

docs/_partials/billing/use-checkout-options.mdx

@@ -0,0 +1,20 @@
+<Properties>
+  - `for?`
+  - `'user' | 'organization'`
+
+  Specifies if the checkout is for an organization. If omitted, the checkout defaults to the current user.
+
+  ---
+
+  - `planId`
+  - `string`
+
+  The ID of the subscription plan to check out (e.g. `cplan_xxx`).
+
+  ---
+
+  - `planPeriod`
+  - `'month' | 'annual'`
+
+  The billing period for the plan.
+</Properties>

docs/billing/b2b-saas.mdx

@@ -1,7 +1,7 @@
 ---
 title: Clerk billing for B2B SaaS
 description: Clerk billing is a feature that allows you to create and manage plans and features for your application.
-sdk: nextjs, react, expo, react-router, astro, tanstack-react-start, remix, nuxt, vue, js-frontend, expressjs, fastify, js-backend 
+sdk: nextjs, react, expo, react-router, astro, tanstack-react-start, remix, nuxt, vue, js-frontend, expressjs, fastify, js-backend
 ---
 
 <Include src="_partials/billing/billing-experimental" />
@@ -42,7 +42,7 @@ You can add a feature to a plan when you are creating a plan. To add it after a
 
 ## Create a pricing page
 
-You can create a pricing page by using the [`<PricingTable />`](/docs/components/pricing-table) component. This component displays a table of plans and features that customers can subscribe to. **It's recommended to create a dedicated page**, as shown in the following example.
+You can create a pricing page by using the [`<PricingTable />`](/docs/components/billing/pricing-table) component. This component displays a table of plans and features that customers can subscribe to. **It's recommended to create a dedicated page**, as shown in the following example.
 
 <Include src="_partials/billing/create-an-organization-pricing-table" />
 

docs/billing/b2c-saas.mdx

@@ -1,7 +1,7 @@
 ---
 title: Clerk billing for B2C SaaS
 description: Clerk billing is a feature that allows you to create and manage plans and features for your application.
-sdk: nextjs, react, expo, react-router, astro, tanstack-react-start, remix, nuxt, vue, js-frontend, expressjs, fastify, js-backend 
+sdk: nextjs, react, expo, react-router, astro, tanstack-react-start, remix, nuxt, vue, js-frontend, expressjs, fastify, js-backend
 ---
 
 <Include src="_partials/billing/billing-experimental" />
@@ -42,7 +42,7 @@ You can add a feature to a plan when you are creating a plan. To add it after a
 
 ## Create a pricing page
 
-You can create a pricing page by using the [`<PricingTable />`](/docs/components/pricing-table) component. This component displays a table of plans and features that users can subscribe to. **It's recommended to create a dedicated page**, as shown in the following example.
+You can create a pricing page by using the [`<PricingTable />`](/docs/components/billing/pricing-table) component. This component displays a table of plans and features that users can subscribe to. **It's recommended to create a dedicated page**, as shown in the following example.
 
 <Include src="_partials/billing/create-a-pricing-table" />
 

docs/billing/overview.mdx

@@ -15,4 +15,11 @@ Clerk billing allows your customers to purchase recurring subscriptions to your
 
   - [Billing for B2B SaaS](/docs/billing/b2b-saas)
   - To charge companies or organizations
+
+  ---
+
+  - [Build a simple checkout page](/docs/custom-flows/checkout-new-payment-method)
+  - To charge users with a new payment method
+
+  ---
 </Cards>

docs/components/checkout-button.mdx → docs/components/billing/checkout-button.mdx

@@ -27,8 +27,8 @@ The `<CheckoutButton />` component renders a button that opens the checkout draw
 
   ---
 
-  - `subscriberType?`
-  - `'user' | 'org'`
+  - `for?`
+  - `'user' | 'organization'`
 
   Determines whether the subscription is for the current user or organization. Defaults to `'user'`.
 
@@ -78,14 +78,14 @@ The `<CheckoutButton />` component renders a button that opens the checkout draw
 </>
 ```
 
-`<CheckoutButton />` will throw an error if the `subscriberType` property is set to `'org'` and no [active organization](/docs/organizations/overview#active-organization) is set.
+`<CheckoutButton />` will throw an error if the `for` prop is set to `'organization'` and no [active organization](/docs/organizations/overview#active-organization) is set.
 
 ```tsx
 <>
   // ❌ This will throw an error if no organization is active
-  <CheckoutButton planId="cplan_xxx" subscriberType="org" />
+  <CheckoutButton planId="cplan_xxx" for="organization" />
   // ✅ Correct usage
-  {auth.orgId ? <CheckoutButton planId="cplan_xxx" subscriberType="org" /> : null}
+  {auth.orgId ? <CheckoutButton planId="cplan_xxx" for="organization" /> : null}
 </>
 ```
 

docs/components/subscription-details-button.mdx → docs/components/billing/subscription-details-button.mdx

@@ -16,7 +16,7 @@ All props are optional.
 
 <Properties>
   - `for?`
-  - `'user' | 'org'`
+  - `'user' | 'organization'`
 
   Determines whether to show subscription details for the current user or organization. Defaults to `'user'`.
 
@@ -59,14 +59,14 @@ All props are optional.
 </>
 ```
 
-`<SubscriptionDetailsButton />` will throw an error if the `for` property is set to `'org'` and no [active organization](/docs/organizations/overview#active-organization) is set.
+`<SubscriptionDetailsButton />` will throw an error if the `for` prop is set to `'organization'` and no [active organization](/docs/organizations/overview#active-organization) is set.
 
 ```tsx
 <>
   // ❌ This will throw an error if no organization is active
-  <SubscriptionDetailsButton for="org" />
+  <SubscriptionDetailsButton for="organization" />
   // ✅ Correct usage
-  {auth.orgId ? <SubscriptionDetailsButton for="org" /> : null}
+  {auth.orgId ? <SubscriptionDetailsButton for="organization" /> : null}
 </>
 ```
 

docs/custom-flows/add-new-payment-method.mdx

@@ -0,0 +1,33 @@
+---
+title: Build a custom flow for adding a new payment method
+description: Learn how to use the Clerk API to build a custom flow for adding a new payment method to a user's account.
+---
+
+<Include src="_partials/custom-flows-callout" />
+
+<Include src="_partials/billing/api-experimental-guide" />
+
+This guide will walk you through how to build a custom user interface that allows users to **add a new payment method to their account**. This is a common feature in a user's billing or account settings page, allowing them to pre-emptively add a payment method for future use.
+
+For the custom flow that allows users to add a new payment method **during checkout**, see the [dedicated guide](/docs/custom-flows/checkout-new-payment-method).
+
+<Steps>
+  ### Enable billing features
+
+  To use billing features, you first need to ensure they are enabled for your application. Follow the [Billing documentation](/docs/billing/overview) to enable them and set up your plans.
+
+  ### Add payment method flow
+
+  To add a new payment method for a user, you must:
+
+  1. Set up the [`<PaymentElementProvider />`](/docs/hooks/use-payment-element) to create a context for the user's payment actions.
+  1. Render the [`<PaymentElement />`](/docs/hooks/use-payment-element) to display the secure payment fields from your provider.
+  1. Use the [`usePaymentElement()`](/docs/hooks/use-payment-element) hook to submit the form and create a payment token.
+  1. Use the [`useUser()`](/docs/hooks/use-user) hook to attach the newly created payment method to the user.
+
+  <Tabs items={["Next.js"]}>
+    <Tab>
+      <Include src="_partials/billing/add-new-payment-method" />
+    </Tab>
+  </Tabs>
+</Steps>