Skip to main content
The subscription hooks let you list, inspect, and manage subscriptions directly from React components. Query hooks fetch data from the plugin’s endpoints and cache it through TanStack Query. Mutation hooks wrap actions like upgrading, cancelling, and resuming, and they automatically invalidate related query keys on success.

Query hooks

useSubscriptionList

Fetch the subscriptions for the current user or a specific reference.
Returns an array of local subscription objects. Each object includes 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 example sub_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. Call mutate(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.
On success, the returned data includes 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.