Skip to main content
Docs

useCheckout()

Warning

This API is experimental and subject to change while Clerk Billing is under Beta. 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

useCheckout() accepts a single object with the following properties:

  • Name
    options?
    Type
    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. If omitted, the checkout defaults to the current 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 a { checkout } object. The checkout object contains the following properties. They are null until the checkout process is started by calling the start() method.

  • Name
    id
    Type
    string | null
    Description

    The unique identifier for the checkout session.

  • Name
    externalClientSecret
    Type
    string | null
    Description

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

  • Name
    externalGatewayId
    Type
    string | null
    Description

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

  • Name
    paymentSource
    Type
    | null
    Description

    The payment source being used for the checkout.

  • Name
    plan
    Type
    | null
    Description

    The subscription plan details for the checkout.

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

    The billing period for the plan.

  • Name
    planPeriodStart
    Type
    number | undefined
    Description

    The start date of the plan period, represented as a Unix timestamp.

  • Name
    status
    Type
    'needs_initialization' | 'needs_confirmation' | 'completed'
    Description

    The current status of the checkout session. The following statuses are possible:

    • needs_initialization: The checkout hasn't started but the hook is mounted. Call start() to continue.
    • needs_confirmation: The checkout has been initialized and is awaiting confirmation. Call confirm() to continue.
    • completed: The checkout has been successfully confirmed. Call finalize() to complete the checkout.
  • Name
    totals
    Type
    Description

    The total costs, taxes, and other pricing details.

  • Name
    isImmediatePlanChange
    Type
    boolean
    Description

    A boolean that indicates if the plan change will take effect immediately.

  • Name
    isStarting
    Type
    boolean
    Description

    A boolean that indicates if the start() method is in progress.

  • Name
    isConfirming
    Type
    boolean
    Description

    A boolean that indicates if the confirm() method is in progress.

  • Name
    error
    Type
    | null
    Description

    Returns an error object if any part of the checkout process fails.

  • Name
    fetchStatus
    Type
    'idle' | 'fetching' | 'error'
    Description

    The data fetching status.

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

    A function that initializes the checkout process by creating a checkout resource on the server.

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

    A function that confirms and finalizes the checkout process, usually after the user has provided and validated payment information.

  • Name
    finalize()
    Type
    (params?: { redirectUrl: string }) => void
    Description

    A function that finalizes the checkout process. Can optionally accept a redirectUrl to navigate the user to upon completion.

  • Name
    clear()
    Type
    () => void
    Description

    A function that clears the current checkout state from the cache.

<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

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

    Specifies if the checkout is for an organization. If omitted, the checkout defaults to the current 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 <SignedIn> components. This ensures that the user is properly authenticated and Clerk is fully initialized before accessing checkout functionality.

function CheckoutPage() {
  return (
    <ClerkLoaded>
      <SignedIn>
        <YourCheckoutComponent />
      </SignedIn>
    </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/nextjs/experimental'
import { ClerkLoaded } from '@clerk/nextjs'
import { CheckoutFlow } from './CheckoutFlow'

export function SubscriptionPage() {
  // `<CheckoutProvider />` sets the context for the checkout flow.
  // Any child component can now call `useCheckout()` to access this context.
  return (
    <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
'use client'

import { useCheckout } from '@clerk/nextjs/experimental'

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

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

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

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

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

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

  const { isConfirming, confirm, finalize, error } = checkout

  const [isProcessing, setIsProcessing] = useState(false)
  const [paymentMethodId, setPaymentMethodId] = useState<string | null>(null)

  const submitSelectedMethod = async () => {
    if (isProcessing || !paymentMethodId) return
    setIsProcessing(true)

    try {
      // Confirm checkout with payment method
      await confirm({
        paymentSourceId: paymentMethodId,
      })
      // 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.
      finalize({ redirectUrl: '/dashboard' })
    } catch (error) {
      console.error('Payment failed:', error)
    } finally {
      setIsProcessing(false)
    }
  }

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

      {error && <div>{error.message}</div>}

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

function CheckoutSummary() {
  const { checkout } = useCheckout()
  const { plan, totals } = checkout

  return (
    <div>
      <h2>Order Summary</h2>
      <span>{plan?.name}</span>
      <span>
        {totals?.totalDueNow.currencySymbol}
        {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
'use client'

import { useCheckout } from '@clerk/nextjs/experimental'

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

  const { start, status, isStarting, error } = checkout

  const handleStartCheckout = async () => {
    try {
      await start()
      // 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>
      {error && <p style={{ color: 'red' }}>Error: {error.errors[0].message}</p>}
    </div>
  )
}

Checkout flow with a new payment method

Prompt users to add a new payment method during checkout

Checkout flow for returning users

Prompt users to select an existing payment method during checkout

Feedback

What did you think of this content?

Last updated on