āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā ā š shadcn/directory/clerk/clerk-docs/reference/hooks/use-subscription ā āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā
useSubscription()'
description: Access subscription information in your React application with Clerk's useSubscription() hook.
sdk: nextjs, reactThe 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 thehas()helper or the<Protect>component instead.
useSubscription() accepts a single optional object with the following properties:
Specifies whether to fetch subscription for an organization or user. Defaults to 'user'.
keepPreviousData?booleanWhen true, the previous data will be kept in the cache until new data is fetched. This helps prevent layout shifts. Defaults to false.
</Properties>
useSubscription() returns an object with the following properties:
The subscription object, or null if the data hasn't been loaded yet.
isLoadingbooleanA boolean that indicates whether the initial data is still being fetched.
isFetchingbooleanA boolean that indicates whether any request is still in flight, including background updates.
errorError | nullAny error that occurred during the data fetch, or null if no error occurred.
revalidate() => Promise<void>Function to manually trigger a refresh of the subscription data. </Properties>
The following example shows how to fetch and display subscription information.
'use client'
import { useSubscription } from '@clerk/nextjs/experimental'
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>
)
}
The following example shows how to fetch an organization's subscription.
'use client'
import { useSubscription } from '@clerk/nextjs/experimental'
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>
)
}
The following example shows how to handle subscription data with proper error states.
'use client'
import { useSubscription } from '@clerk/nextjs/experimental'
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.amountFormatted}</p>
<p>Due: {subscription.nextPayment.date.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>
)
}
export default function Page() {
const { data, isLoading, error, isFetching, revalidate } = 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 ? <SubscriptionDetails /> : <div>No active subscription</div>}
</>
)}
</div>
)
}
ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā