Skip to main content
Docs

usePlans()

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 usePlans() hook provides access to the subscription plans available in your application. It returns a paginated list of plans and includes methods for managing them.

Parameters

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

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

    Specifies whether to fetch plans for users or organizations. Defaults to 'user'.

  • Name
    pageSize?
    Type
    number
    Description

    The number of plans to fetch per page. Defaults to 10.

  • Name
    initialPage?
    Type
    number
    Description

    The page number to start fetching from. Defaults to 1.

  • Name
    infinite?
    Type
    boolean
    Description

    When true, enables infinite pagination mode where new pages are appended to existing data. When false, each page replaces the previous data. Defaults to false.

  • Name
    keepPreviousData?
    Type
    boolean
    Description

    When true, the previous data will be kept while loading the next page. This helps prevent layout shifts. Defaults to false.

Returns

The hook returns an object with the following properties:

  • Name
    data
    Type
    Plan[] | null
    Description

    An array of plan objects, or null if the data hasn't been loaded yet.

  • Name
    isLoading
    Type
    boolean
    Description

    A boolean that indicates whether the initial data is still being fetched.

  • Name
    isFetching
    Type
    boolean
    Description

    A boolean that indicates whether any request is still in flight, including background updates.

  • Name
    hasNextPage
    Type
    boolean
    Description

    A boolean that indicates whether there are more pages available to load.

  • Name
    hasPreviousPage
    Type
    boolean
    Description

    A boolean that indicates whether there are previous pages available to load.

  • Name
    fetchNext
    Type
    () => Promise<void>
    Description

    Function to fetch the next page of plans.

  • Name
    fetchPrevious
    Type
    () => Promise<void>
    Description

    Function to fetch the previous page of plans.

  • Name
    pageCount
    Type
    number
    Description

    The total number of available pages.

  • Name
    count
    Type
    number
    Description

    The total number of plans available.

Plan

Each plan object contains the following properties:

  • Name
    id
    Type
    string
    Description

    The unique identifier for the plan (e.g., cplan_xxxx).

  • Name
    name
    Type
    string
    Description

    The display name of the plan.

  • Name
    description
    Type
    string
    Description

    A detailed description of what the plan offers.

  • Name
    amount
    Type
    number
    Description

    The cost of the plan in cents.

  • Name
    currency
    Type
    string
    Description

    The three-letter ISO currency code (e.g., 'USD', 'EUR').

  • Name
    interval
    Type
    'monthly' | 'yearly'
    Description

    The billing interval for the plan.

  • Name
    features
    Type
    PlanFeature[]
    Description

    An array of features included in the plan.

  • Name
    isPublic
    Type
    boolean
    Description

    Whether the plan is publicly available and visible in components like <PricingTable />.

PlanFeature

Each feature object contains the following properties:

  • Name
    id
    Type
    string
    Description

    The unique identifier for the feature.

  • Name
    name
    Type
    string
    Description

    The display name of the feature.

  • Name
    description
    Type
    string
    Description

    A detailed description of what the feature provides.

Examples

Basic usage

The following example shows how to fetch and display available plans.

import { usePlans } from '@clerk/nextjs'

function PlansList() {
  const { data, isLoading } = usePlans({
    for: 'user',
    pageSize: 10,
  })

  if (isLoading) {
    return <div>Loading plans...</div>
  }

  return (
    <ul>
      {data?.map((plan) => (
        <li key={plan.id}>
          <h3>{plan.name}</h3>
          <p>{plan.description}</p>
          <p>
            {(plan.amount / 100).toFixed(2)} {plan.currency} / {plan.interval}
          </p>
          <h4>Features:</h4>
          <ul>
            {plan.features.map((feature) => (
              <li key={feature.id}>{feature.name}</li>
            ))}
          </ul>
        </li>
      ))}
    </ul>
  )
}

Feedback

What did you think of this content?

Last updated on