Query hooks
useSubscriptionList
Fetch the subscriptions for the current user or a specific reference.id, plan, status, razorpaySubscriptionId, shortUrl, currentStart, currentEnd, quantity, trialStart, trialEnd, and more.
useSubscription
Fetch a single local subscription by its id.useRazorpaySubscription
Fetch the raw Razorpay subscription object by its Razorpay id (for examplesub_XXXX).
useRazorpaySubscriptions
List subscriptions directly from Razorpay with optional filters.useRazorpayInvoices
Fetch invoices associated with a Razorpay subscription.useSubscriptionPendingUpdate
Check whether a subscription has a pending update scheduled.useRazorpayPlans
List all Razorpay plans.Mutation hooks
All mutation hooks return a TanStack Query mutation object. Callmutate(body) or mutateAsync(body) to trigger the action. They invalidate razorpayQueryKeys.subscriptions() and related keys on success.
useUpgradeSubscription
Upgrade or create a subscription for a plan.subscription (local row) and razorpaySubscription (Razorpay object). The shortUrl field is the hosted authorization link you can redirect the user to.
useCancelSubscription
Cancel an active subscription immediately or at the end of the current billing cycle.usePauseSubscription
Pause an active subscription.useResumeSubscription
Resume a paused subscription.useRestoreSubscription
Restore a subscription that is scheduled to cancel at the end of the current cycle.useUpdateSubscription
Update an existing subscription with a new plan, offer, quantity, or metadata.Full billing settings page example
The following component shows the current subscription, lists available plans, and lets the user cancel, resume, or restore their subscription.app/billing/page.tsx
The
useSubscriptionStatus helper is documented on the Subscription status page. It returns boolean flags you can use to gate UI without duplicating status logic.