# useCheckout() > Billing regularly introduces new features and UI changes to Clerk's components. If you'd like to remain on a specific version of Clerk's components or SDK, you can follow the steps in the [pinning](https://clerk.com/docs/pinning.md?sdk=nextjs) documentation. 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 [](https://clerk.com/docs/nextjs/reference/hooks/use-checkout.md#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 | Parameter | Type | Description | | ---------- | ---------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `options?` | `PropsWithChildren`<[UseCheckoutOptions](https://clerk.com/docs/nextjs/reference/hooks/use-checkout.md#usecheckoutoptions)> | An object containing the configuration for the checkout flow. **Required** if the hook is used without a `` wrapping the component tree. | ### `UseCheckoutOptions` | Property | Type | Description | | ------------------------------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------- | | `for?` | `"user" | "organization"` | Specifies if the checkout is for an Organization. Defaults to `'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. | | `priceId?` | `string` | The specific price ID to check out for, used when the desired price ID is not the current default price | | `seatsQuantity?` | `number` | The number of total seats to check out for | ## 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. | Property | Type | Description | | -------------------------------------- | ---------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | | `checkout` | [CheckoutFlowResource](https://clerk.com/docs/nextjs/reference/hooks/use-checkout.md#checkoutflowresource) | An instance representing the currently active `Checkout`. | | `errors` | `CheckoutErrors` | Represents the errors that occurred during the last fetch of the parent resource. | | `fetchStatus` | `"idle" | "fetching"` | The fetch status of the underlying `Checkout` resource. | ## `CheckoutFlowResource` | Property | Type | Description | | ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `confirm` | (params: ConfirmCheckoutParams) => Promise<{ error: null | ClerkError; }> | A function to confirm and finalize the checkout process, usually after payment information has been provided and validated. [Learn more.](https://clerk.com/docs/nextjs/reference/types/billing-checkout-resource.md#confirm) | | `externalClientSecret` | `null | string` | A client secret from an external payment provider (such as Stripe) used to complete the payment on the client-side. | | `externalGatewayId` | `null | string` | The identifier for the external payment gateway used for this checkout session. | | `finalize` | (params?: CheckoutFlowFinalizeParams) => Promise<{ error: null | ClerkError; }> | 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. | | `freeTrialEndsAt?` | `null | Date` | Unix timestamp (milliseconds) of when the free trial ends. | | `isImmediatePlanChange` | `null | boolean` | Whether the plan change will take effect immediately after checkout. | | `needsPaymentMethod` | `null | boolean` | Whether a payment method is required for this checkout. | | `payer` | `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; }` | Example: ``. | | `payer.createdAt?` | `Date` | The date and time when the payer was created. | | `payer.email?` | `null | string` | The email address of the payer. | | `payer.firstName?` | `null | string` | The first name of the payer. | | `payer.id` | `string` | The unique identifier for the payer. | | `payer.imageUrl?` | `string` | The URL of the payer's avatar image. | | `payer.lastName?` | `null | string` | The last name of the payer. | | `payer.organizationId` | `null | string` | The unique identifier for the Organization that the payer belongs to. | | `payer.organizationName?` | `null | string` | The name of the Organization that the payer belongs to. | | `payer.pathRoot` | `string` | - | | `payer.updatedAt?` | `Date` | The date and time when the payer was last updated. | | `payer.userId` | `null | string` | The unique identifier for the payer. | | `paymentMethod` | `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; }` | The payment source being used for the checkout, such as a credit card or bank account. | | `paymentMethod.cardType` | `null | string` | The brand or type of card. For example, `'visa'` or `'mastercard'`. | | `paymentMethod.createdAt?` | `null | Date` | The date the payment method was created, if available. | | `paymentMethod.expiryMonth?` | `null | number` | The card expiration month, if available. | | `paymentMethod.expiryYear?` | `null | number` | The card expiration year, if available. | | `paymentMethod.id` | `string` | The unique identifier for the payment method. | | `paymentMethod.isDefault?` | `boolean` | Whether the payment method is set as the default for the account. | | `paymentMethod.isRemovable?` | `boolean` | Whether the payment method can be removed by the user. | | `paymentMethod.last4` | `null | string` | The last four digits of the payment method. | | `paymentMethod.pathRoot` | `string` | - | | `paymentMethod.paymentType?` | `"card"` | The type of payment method. For example, `'card'`. | | `paymentMethod.status` | `"active" | "expired" | "disconnected"` | The current status of the payment method. | | `paymentMethod.updatedAt?` | `null | Date` | The date the payment method was last updated, if available. | | `paymentMethod.walletType?` | `null | string` | The type of digital wallet, if applicable. For example, `'apple_pay'`, or `'google_pay'`. | | `plan` | null | { annualFee: null | BillingMoneyAmount; annualMonthlyFee: null | BillingMoneyAmount; availablePrices?: BillingPlanPrice[]; 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; unitPrices?: BillingPlanUnitPrice[]; } | The subscription plan details for the checkout. | | `plan.annualFee` | null | BillingMoneyAmount | The annual price of the Plan or `null` if the Plan is not annual. | | `plan.annualMonthlyFee` | null | BillingMoneyAmount | The effective monthly price when billed annually or `null` if the Plan is not annual. | | `plan.availablePrices?` | BillingPlanPrice[] | The prices that are available to be used to checkout for the associated plan. Can be used to select non-default prices. | | `plan.avatarUrl` | `null | string` | The URL of the Plan's avatar image, or `null` if not set. | | `plan.description` | `null | string` | A short description of what the Plan offers, or `null` if no description is provided. | | `plan.features` | FeatureResource[] | The Features the Plan offers. | | `plan.fee` | null | BillingMoneyAmount | The monthly price of the Plan. | | `plan.forPayerType` | `"org" | "user"` | Specifies the subscriber type this Plan is designed for. Each Plan is exclusively created for either individual users or Organizations, and cannot be used interchangeably. | | `plan.freeTrialDays` | `null | number` | The number of days of the free trial for the Plan. `null` if the Plan does not have a free trial. | | `plan.freeTrialEnabled` | `boolean` | Whether the Plan has a free trial. | | `plan.hasBaseFee` | `boolean` | Whether the Plan has a base fee. | | `plan.id` | `string` | The unique identifier for the Plan. | | `plan.isDefault` | `boolean` | Whether the Plan is the default Plan. | | `plan.isRecurring` | `boolean` | Whether the Plan is recurring. | | `plan.name` | `string` | The name of the Plan. | | `plan.pathRoot` | `string` | - | | `plan.publiclyVisible` | `boolean` | Whether the Plan is visible to the public. | | `plan.slug` | `string` | The URL-friendly identifier of the Plan. | | `plan.unitPrices?` | BillingPlanUnitPrice[] | Per-unit pricing tiers for this Plan (e.g., seats). | | `planPeriod` | `null | "month" | "annual"` | The billing period for the plan. | | `planPeriodStart` | `undefined | null | number` | Unix timestamp (milliseconds) of when the current period starts. | | `start` | () => Promise<{ error: null | ClerkError; }> | Example: ``. | | `totals` | null | BillingTotals | The total costs, taxes, and other pricing details for the checkout. | | `update` | (params: Pick<UpdateCheckoutParams, "promoCode">) => Promise<{ error: null | ClerkError; }> | Updates the current checkout. Use an empty promo code to remove the applied promo code. [Learn more.](https://clerk.com/docs/nextjs/reference/types/billing-checkout-resource.md#update) | ## `` The `` 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 `` component accepts the following props: | Property | Type | Description | | ------------------------------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------- | | `for?` | `"user" | "organization"` | Specifies if the checkout is for an Organization. Defaults to `'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. | | `priceId?` | `string` | The specific price ID to check out for, used when the desired price ID is not the current default price | | `seatsQuantity?` | `number` | The number of total seats to check out for | ## Usage For the best user experience and to prevent potential errors, always wrap components using `useCheckout()` with both `` and `` components. This ensures that the user is properly authenticated and Clerk is fully initialized before accessing checkout functionality. ```tsx function CheckoutPage() { return ( ) } ``` ### 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. **With ** The following example shows the basic structure for a checkout flow. A parent component, ``, sets up the `` and renders the checkout flow. A child component, ``, uses the `useCheckout()` hook to access the checkout state. **** filename: src/components/SubscriptionPage.tsx ```tsx import { CheckoutProvider } from '@clerk/nextjs/experimental' import { ClerkLoaded } from '@clerk/nextjs' import { CheckoutFlow } from './CheckoutFlow' export default function SubscriptionPage() { // `` 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

Upgrade Your Plan

You are about to subscribe to our monthly plan

 ) } ``` **** filename: src/components/CheckoutFlow\.tsx ```tsx '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 } return (
) } function CheckoutInitialization() { const { checkout, fetchStatus } = useCheckout() return ( ) } function PaymentSection() { const { checkout, errors, fetchStatus } = useCheckout() const [paymentMethodId, setPaymentMethodId] = useState(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 */} {errors.global && (
    {errors.global.map((error, index) => (
  • {error.longMessage || error.message}
    • ))}
)} ) } function CheckoutSummary() { const { checkout } = useCheckout() return (

Order Summary

{checkout.plan?.name} {checkout.totals?.totalDueNow.currencySymbol} {checkout.totals?.totalDueNow.amountFormatted}
) } ``` **Standalone Hook** 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 `` component that manages its own checkout flow. filename: src/components/UpgradeButton.tsx ```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 (
{errors.global && (
    {errors.global.map((error, index) => (
  • {error.longMessage || error.message}
    • ))}
)}
) } ``` ## Next steps - [Checkout flow with a new payment method](https://clerk.com/docs/guides/development/custom-flows/billing/checkout-new-payment-method.md?sdk=nextjs): Build a custom checkout flow that allows users to add a new payment method during checkout. - [Checkout flow for returning users](https://clerk.com/docs/guides/development/custom-flows/billing/checkout-existing-payment-method.md?sdk=nextjs): Build a custom checkout flow that allows users to select an existing payment method during checkout. --- ## Sitemap [Overview of all docs pages](https://clerk.com/docs/llms.txt)