`useSubscription()`

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 useSubscription() hook provides access to subscription information for users or organizations in your application. It returns the current subscription data and includes methods for managing it.

Warning

The useSubscription() hook should only be used for accessing and displaying subscription information. For authorization purposes (i.e., controlling access to features or content), use the has() helper or the <Protect> component instead.

Parameters

useSubscription() accepts a single optional object with the following properties:

Name
for?
Type
'organization' | 'user'
Description
Specifies whether to fetch subscription for an organization or user. Defaults to 'user'.
Name
keepPreviousData?
Type
boolean
Description
When true, the previous data will be kept in the cache until new data is fetched. This helps prevent layout shifts. Defaults to false.

Returns

Name
data
Type
Subscription | null
Description
The subscription object, 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
error
Type
Error | null
Description
Any error that occurred during the data fetch, or null if no error occurred.
Name
revalidate
Type
() => Promise<void>
Description
Function to manually trigger a refresh of the subscription data.

`Subscription`

Each subscription object contains the following properties:

Name
id
Type
string
Description
The unique identifier for the subscription.
Name
status
Type
CommerceSubscriptionStatus
Description
The current status of the subscription.
Name
activeAt
Type
Date
Description
The date when the subscription became active.
Name
createdAt
Type
Date
Description
The date when the subscription was created.
Name
updatedAt
Type
Date | null
Description
The date when the subscription was last updated, or null if never updated.
Name
pastDueAt
Type
Date | null
Description
The date when the subscription became past due, or null if not past due.
Name
nextPayment
Type
{ amount: CommerceMoney; time: Date; } | null
Description
Information about the next payment, including the amount and scheduled time. Returns null if no upcoming payment.
Name
subscriptionItems
Type
CommerceSubscriptionItemResource[]
Description
An array of items included in this subscription.

Examples

Basic usage

The following example shows how to fetch and display subscription information.

import { useSubscription } from '@clerk/nextjs'

function SubscriptionInfo() {
  const { data, isLoading, error } = useSubscription()

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

  if (error) {
    return <div>Error loading subscription: {error.message}</div>
  }

  if (!data) {
    return <div>No subscription found</div>
  }

  return (
    <div>
      <h2>Your Subscription</h2>
      {/* Display subscription details */}
    </div>
  )
}

Organization subscription

The following example shows how to fetch an organization's subscription.

import { useSubscription } from '@clerk/nextjs'

function OrganizationSubscription() {
  const { data, isLoading, revalidate } = useSubscription({
    for: 'organization',
    keepPreviousData: true,
  })

  const handleSubscriptionUpdate = async () => {
    // After making changes to the subscription
    await revalidate()
  }

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

  return (
    <div>
      <h2>Organization Subscription</h2>
      {/* Display organization subscription details */}
      <button onClick={handleSubscriptionUpdate}>Refresh Subscription</button>
    </div>
  )
}

With error handling

The following example shows how to handle subscription data with proper error states.

import { useSubscription } from '@clerk/nextjs'

function SubscriptionStatus() {
  const { data, isLoading, error, isFetching } = useSubscription()

  if (error) {
    return (
      <div className="error-state">
        <h3>Failed to load subscription</h3>
        <p>{error.message}</p>
        <button onClick={revalidate}>Try Again</button>
      </div>
    )
  }

  return (
    <div className="subscription-status">
      {isLoading ? (
        <div>Loading...</div>
      ) : (
        <>
          <div className="status-indicator">{isFetching && <span>Refreshing...</span>}</div>
          {data ? (
            <div className="subscription-details">{/* Display subscription details */}</div>
          ) : (
            <div>No active subscription</div>
          )}
        </>
      )}
    </div>
  )
}

import { useSubscription } from '@clerk/nextjs'

function SubscriptionDetails() {
  const { data: subscription, isLoading } = useSubscription()

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

  if (!subscription) {
    return <div>No subscription</div>
  }

  return (
    <div className="subscription-details">
      <h2>Subscription Details</h2>
      <div className="status">
        Status: <span className={`status-${subscription.status}`}>{subscription.status}</span>
      </div>

      <div className="dates">
        <p>Active since: {subscription.activeAt.toLocaleDateString()}</p>
        {subscription.pastDueAt && (
          <p className="warning">Past due since: {subscription.pastDueAt.toLocaleDateString()}</p>
        )}
      </div>

      {subscription.nextPayment && (
        <div className="next-payment">
          <h3>Next Payment</h3>
          <p>Amount: {subscription.nextPayment.amount}</p>
          <p>Due: {subscription.nextPayment.time.toLocaleDateString()}</p>
        </div>
      )}

      <div className="subscription-items">
        <h3>Subscription Items</h3>
        <ul>
          {subscription.subscriptionItems.map((item) => (
            <li key={item.id}>{/* Display subscription item details */}</li>
          ))}
        </ul>
      </div>
    </div>
  )
}

Edit this page on GitHub

Last updated on Jul 24, 2025

useSubscription()