Skip to main content
Docs

useCheckout()

Warning

Billing is currently in Beta and its APIs are experimental and may undergo breaking changes. To mitigate potential disruptions, we recommend pinning your SDK and clerk-js package versions.

The useCheckout() hook is used to create, manage, and confirm a checkout session for a user or an Organization's Subscription Plan. It provides the state of the current checkout process, such as its status and any errors, along with methods to initiate and complete the checkout.

There are two ways to use useCheckout():

  1. In conjunction with <CheckoutProvider /> to create a shared checkout context. All child components inside the provider can then use useCheckout() to access or update the same checkout state.
  2. On its own by passing configuration options directly to it. This is ideal for self-contained components that handle their own checkout flow without needing a shared context.

Parameters

  • Name
    options?
    Type
    PropsWithChildren<UseCheckoutOptions>
    Description

    An object containing the configuration for the checkout flow. Required if the hook is used without a <CheckoutProvider /> wrapping the component tree.

  • Name
    for?
    Type
    "user" | "organization"
    Description

    Specifies if the checkout is for an Organization. Defaults to 'user'.

  • Name
    planId
    Type
    string
    Description

    The ID of the Subscription Plan to check out (e.g. cplan_xxx).

  • Name
    planPeriod
    Type
    "month" | "annual"
    Description

    The billing period for the Plan.

Returns

useCheckout() returns an object with checkout, errors, and fetchStatus.

  • checkout includes the checkout state and methods.
  • errors contains any global or raw errors from the latest checkout request.
  • fetchStatus indicates whether the checkout request is currently in progress.

Checkout data properties are null until the checkout process is started by calling the start() method.

  • Name
    checkout
    Type
    CheckoutFlowResource
    Description

    An instance representing the currently active Checkout.

  • Name
    errors
    Type
    CheckoutErrors
    Description

    Represents the errors that occurred during the last fetch of the parent resource.

  • Name
    fetchStatus
    Type
    "idle" | "fetching"
    Description

    The fetch status of the underlying Checkout resource.

  • Name
    confirm
    Type
    (params: ConfirmCheckoutParams) => Promise<{ error: null | ClerkError; }>
    Description

    A function to confirm and finalize the checkout process, usually after payment information has been provided and validated. Learn more.

  • Name
    externalClientSecret
    Type
    null | string
    Description

    A client secret from an external payment provider (such as Stripe) used to complete the payment on the client-side.

  • Name
    externalGatewayId
    Type
    null | string
    Description

    The identifier for the external payment gateway used for this checkout session.

  • Name
    finalize
    Type
    (params?: CheckoutFlowFinalizeParams) => Promise<{ error: null | ClerkError; }>
    Description

    Used to convert a checkout with status === 'completed' into an active subscription. Will cause anything observing the subscription state (such as the useSubscription() hook) to update automatically.

  • Name
    freeTrialEndsAt?
    Type
    null | Date
    Description

    Unix timestamp (milliseconds) of when the free trial ends.

  • Name
    isImmediatePlanChange
    Type
    null | boolean
    Description

    Whether the plan change will take effect immediately after checkout.

  • Name
    needsPaymentMethod
    Type
    null | boolean
    Description

    Whether a payment method is required for this checkout.

  • Name
    payer
    Type
    null | { createdAt?: Date; email?: null | string; firstName?: null | string; id: string; imageUrl?: string; lastName?: null | string; organizationId: null | string; organizationName?: null | string; pathRoot: string; updatedAt?: Date; userId: null | string; }
    Description

    Example: <ClerkProvider clerkJsVersion="x.x.x" />.

  • Name
    paymentMethod
    Type
    null | { cardType: null | string; createdAt?: null | Date; expiryMonth?: null | number; expiryYear?: null | number; id: string; isDefault?: boolean; isRemovable?: boolean; last4: null | string; pathRoot: string; paymentType?: "card"; status: "active" | "expired" | "disconnected"; updatedAt?: null | Date; walletType?: null | string; }
    Description

    The payment source being used for the checkout, such as a credit card or bank account.

  • Name
    plan
    Type
    null | { annualFee: null | BillingMoneyAmount; annualMonthlyFee: null | BillingMoneyAmount; avatarUrl: null | string; description: null | string; features: FeatureResource[]; fee: null | BillingMoneyAmount; forPayerType: "org" | "user"; freeTrialDays: null | number; freeTrialEnabled: boolean; hasBaseFee: boolean; id: string; isDefault: boolean; isRecurring: boolean; name: string; pathRoot: string; publiclyVisible: boolean; slug: string; }
    Description

    The subscription plan details for the checkout.

  • Name
    planPeriod
    Type
    null | "month" | "annual"
    Description

    The billing period for the plan.

  • Name
    planPeriodStart
    Type
    undefined | null | number
    Description

    Unix timestamp (milliseconds) of when the current period starts.

  • Name
    start
    Type
    () => Promise<{ error: null | ClerkError; }>
    Description

    Example: <ClerkProvider clerkJsVersion="x.x.x" />.

  • Name
    totals
    Type
    null | BillingCheckoutTotals
    Description

    The total costs, taxes, and other pricing details for the checkout.

<CheckoutProvider />

The <CheckoutProvider /> component is a wrapper that provides a checkout context to its children, allowing checkout state to be shared across multiple components. Child components can access the checkout context by calling useCheckout().

Properties

The <CheckoutProvider /> component accepts the following props:

  • Name
    for?
    Type
    "user" | "organization"
    Description

    Specifies if the checkout is for an Organization. Defaults to 'user'.

  • Name
    planId
    Type
    string
    Description

    The ID of the Subscription Plan to check out (e.g. cplan_xxx).

  • Name
    planPeriod
    Type
    "month" | "annual"
    Description

    The billing period for the Plan.

Usage

For the best user experience and to prevent potential errors, always wrap components using useCheckout() with both <ClerkLoaded> and <Show when="signed-in"> components. This ensures that the user is properly authenticated and Clerk is fully initialized before accessing checkout functionality.

function CheckoutPage() {
  return (
    <ClerkLoaded>
      <Show when="signed-in">
        <YourCheckoutComponent />
      </Show>
    </ClerkLoaded>
  )
}

Examples

The useCheckout() hook can be used with a context provider for managing state across multiple components or as a standalone hook for more isolated use cases.

The following example shows the basic structure for a checkout flow. A parent component, <SubscriptionPage />, sets up the <CheckoutProvider /> and renders the checkout flow. A child component, <CheckoutFlow />, uses the useCheckout() hook to access the checkout state.

src/components/SubscriptionPage.tsx
import { CheckoutProvider } from '@clerk/react/experimental'
import { ClerkLoaded } from '@clerk/react'
import { CheckoutFlow } from './CheckoutFlow'

export default function SubscriptionPage() {
  // `<CheckoutProvider />` sets the context for the checkout flow.
  // Any child component can now call `useCheckout()` to access this context.
  return (
    // Update with your Plan ID and Plan Period
    <CheckoutProvider for="user" planId="cplan_xxx" planPeriod="month">
      <div>
        <h1>Upgrade Your Plan</h1>
        <p>You are about to subscribe to our monthly plan</p>
        <ClerkLoaded>
          <CheckoutFlow />
        </ClerkLoaded>
      </div>
    </CheckoutProvider>
  )
}
src/components/CheckoutFlow.tsx
import { useCheckout } from '@clerk/react/experimental'
import { useState } from 'react'
import { useNavigate } from 'react-router-dom'

export function CheckoutFlow() {
  const { checkout } = useCheckout()

  if (checkout.status === 'needs_initialization') {
    return <CheckoutInitialization />
  }

  return (
    <div className="checkout-container">
      <CheckoutSummary />
      <PaymentSection />
    </div>
  )
}

function CheckoutInitialization() {
  const { checkout, fetchStatus } = useCheckout()

  return (
    <button onClick={() => checkout.start()} disabled={fetchStatus === 'fetching'}>
      {fetchStatus === 'fetching' ? 'Initializing...' : 'Start Checkout'}
    </button>
  )
}

function PaymentSection() {
  const { checkout, errors, fetchStatus } = useCheckout()

  const [paymentMethodId, setPaymentMethodId] = useState<string | null>(null)
  const navigate = useNavigate()

  const submitSelectedMethod = async () => {
    if (fetchStatus === 'fetching' || !paymentMethodId) return

    try {
      // Confirm checkout with payment method
      const { error } = await checkout.confirm({
        paymentMethodId,
      })
      if (error) {
        console.error(JSON.stringify(error, null, 2))
        return
      }
      // Calling `.finalize` enables you to sync the client-side state with the server-side state of your users.
      // It revalidates all authorization checks computed within server components.
      await checkout.finalize({
        navigate: ({ decorateUrl }) => {
          const url = decorateUrl('/')
          if (url.startsWith('http')) {
            window.location.href = url
          } else {
            navigate(url)
          }
        },
      })
    } catch (error) {
      console.error('Payment failed:', error)
    }
  }

  return (
    <>
      {/* A component that lists a user's payment methods and allows them to select one. See an example: https://clerk.com/docs/reference/hooks/use-payment-methods#examples */}
      <PaymentMethods onChange={setPaymentMethodId} />

      {errors.global && (
        <ul>
          {errors.global.map((error, index) => (
            <li key={index}>{error.longMessage || error.message}</li>
          ))}
        </ul>
      )}

      <button type="button" disabled={fetchStatus === 'fetching'} onClick={submitSelectedMethod}>
        {fetchStatus === 'fetching' ? 'Processing...' : 'Complete Purchase'}
      </button>
    </>
  )
}

function CheckoutSummary() {
  const { checkout } = useCheckout()

  return (
    <div>
      <h2>Order Summary</h2>
      <span>{checkout.plan?.name}</span>
      <span>
        {checkout.totals?.totalDueNow.currencySymbol}
        {checkout.totals?.totalDueNow.amountFormatted}
      </span>
    </div>
  )
}

For simple, self-contained components, you can use useCheckout() by passing the configuration options directly to the hook. This avoids the need to wrap the component in a provider.

The following example shows an <UpgradeButton /> component that manages its own checkout flow.

src/components/UpgradeButton.tsx
import { useCheckout } from '@clerk/react/experimental'

export function UpgradeButton({
  planId,
  planPeriod,
}: {
  planId: string
  planPeriod: 'month' | 'annual'
}) {
  // Pass options directly to the hook when not using a provider.
  const { checkout, errors, fetchStatus } = useCheckout({
    planId,
    planPeriod,
    for: 'user',
  })

  const isStarting = fetchStatus === 'fetching'

  const handleStartCheckout = async () => {
    try {
      const { error } = await checkout.start()
      if (error) {
        console.error(JSON.stringify(error, null, 2))
        return
      }
      // In a real app, you would now use the `externalClientSecret`
      // from the checkout object to render a payment form.
      console.log('Checkout started! Status:', checkout.status)
    } catch (e) {
      console.error('Error starting checkout:', e)
    }
  }

  return (
    <div>
      <button onClick={handleStartCheckout} disabled={isStarting}>
        {isStarting ? 'Initializing...' : `Upgrade to ${planPeriod} plan`}
      </button>
      {errors.global && (
        <ul>
          {errors.global.map((error, index) => (
            <li key={index}>{error.longMessage || error.message}</li>
          ))}
        </ul>
      )}
    </div>
  )
}

Checkout flow with a new payment method

Build a custom checkout flow that allows users to add a new payment method during checkout.

Checkout flow for returning users

Build a custom checkout flow that allows users to select an existing payment method during checkout.

Feedback

What did you think of this content?

Last updated on