| title | `useCheckout()` |
|---|---|
| description | Clerk's useCheckout() hook provides state and methods to manage a Subscription checkout flow. |
| sdk | nextjs, react |
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():
- In conjunction with
<CheckoutProvider />to create a shared checkout context. All child components inside the provider can then useuseCheckout()to access or update the same checkout state. - 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.
useCheckout() returns an object with checkout, errors, and fetchStatus.
checkoutincludes the checkout state and methods.errorscontains any global or raw errors from the latest checkout request.fetchStatusindicates whether the checkout request is currently in progress.
Checkout data properties are null until the checkout process is started by calling the start() method.
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().
The <CheckoutProvider /> component accepts the following props:
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>
)
}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.
<Tabs items={["With ", "Standalone Hook"]}>
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.
<Tabs items={["<SubscriptionPage />", "<CheckoutFlow />"]}>
<Tab>
<If sdk="nextjs">
```tsx {{ filename: 'src/components/SubscriptionPage.tsx', collapsible: true }}
import { CheckoutProvider } from '@clerk/nextjs/experimental'
import { ClerkLoaded } from '@clerk/nextjs'
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>
)
}
```
</If>
<If sdk="react">
```tsx {{ filename: 'src/components/SubscriptionPage.tsx', collapsible: true }}
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>
)
}
```
</If>
</Tab>
<Tab>
<If sdk="nextjs">
```tsx {{ filename: 'src/components/CheckoutFlow.tsx', collapsible: true }}
'use client'
import { useCheckout } from '@clerk/nextjs/experimental'
import { useState } from 'react'
import { useRouter } from 'next/navigation'
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 router = useRouter()
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 {
router.push(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>
)
}
```
</If>
<If sdk="react">
```tsx {{ filename: 'src/components/CheckoutFlow.tsx', collapsible: true }}
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>
)
}
```
</If>
</Tab>
</Tabs>
The following example shows an `<UpgradeButton />` component that manages its own checkout flow.
<If sdk="nextjs">
```tsx {{ filename: '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, 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>
)
}
```
</If>
<If sdk="react">
```tsx {{ filename: '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>
)
}
```
</If>
- Checkout flow for returning users
- Build a custom checkout flow that allows users to select an existing payment method during checkout.