> ## Documentation Index
> Fetch the complete documentation index at: https://better-auth-razorpay.amankushwaha.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Subscription hooks

> Query and mutate subscriptions with TanStack Query hooks for listing, upgrading, cancelling, pausing, resuming, and restoring.

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.

```tsx theme={null}
import { useSubscriptionList } from "@amank-root/better-auth-razorpay/react";

const { data, isLoading, error } = useSubscriptionList(authClient, {
  referenceId?: string;
  customerType?: "user" | "organization";
  queryOptions?: { staleTime?: number; refetchInterval?: number; /* ... */ };
});
```

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.

```tsx theme={null}
import { useSubscription } from "@amank-root/better-auth-razorpay/react";

const { data, isLoading } = useSubscription(authClient, subscriptionId, {
  referenceId?: string;
  customerType?: "user" | "organization";
  queryOptions?: { /* ... */ };
});
```

### useRazorpaySubscription

Fetch the raw Razorpay subscription object by its Razorpay id (for example `sub_XXXX`).

```tsx theme={null}
import { useRazorpaySubscription } from "@amank-root/better-auth-razorpay/react";

const { data } = useRazorpaySubscription(authClient, "sub_XXXX");
```

### useRazorpaySubscriptions

List subscriptions directly from Razorpay with optional filters.

```tsx theme={null}
import { useRazorpaySubscriptions } from "@amank-root/better-auth-razorpay/react";

const { data } = useRazorpaySubscriptions(authClient, {
  planId?: string;
  status?: "created" | "authenticated" | "active" | "pending" | "halted" | "paused" | "cancelled" | "reverted" | "expired" | "completed";
  expand?: string[];
  from?: number;
  to?: number;
  count?: number;
  skip?: number;
});
```

### useRazorpayInvoices

Fetch invoices associated with a Razorpay subscription.

```tsx theme={null}
import { useRazorpayInvoices } from "@amank-root/better-auth-razorpay/react";

const { data } = useRazorpayInvoices(authClient, "sub_XXXX");
```

### useSubscriptionPendingUpdate

Check whether a subscription has a pending update scheduled.

```tsx theme={null}
import { useSubscriptionPendingUpdate } from "@amank-root/better-auth-razorpay/react";

const { data } = useSubscriptionPendingUpdate(authClient, "sub_XXXX");
```

### useRazorpayPlans

List all Razorpay plans.

```tsx theme={null}
import { useRazorpayPlans } from "@amank-root/better-auth-razorpay/react";

const { data } = useRazorpayPlans(authClient);
```

## 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.

```tsx theme={null}
import { useUpgradeSubscription } from "@amank-root/better-auth-razorpay/react";

const upgrade = useUpgradeSubscription(authClient);

upgrade.mutate({
  plan: "pro",
  referenceId?: "org_XXXX";
  customerType?: "organization";
  annual?: true;
  metadata?: { teamSize: 5 };
  lineItems?: [{ item_id: "item_XXXX", quantity: 2 }];
  scheduleAtPeriodEnd?: false;
});
```

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.

```tsx theme={null}
import { useCancelSubscription } from "@amank-root/better-auth-razorpay/react";

const cancel = useCancelSubscription(authClient);

cancel.mutate({
  referenceId?: string;
  customerType?: "user" | "organization";
  cancelAtCycleEnd?: true; // default false (immediate)
});
```

### usePauseSubscription

Pause an active subscription.

```tsx theme={null}
import { usePauseSubscription } from "@amank-root/better-auth-razorpay/react";

const pause = usePauseSubscription(authClient);

pause.mutate({
  referenceId?: string;
  customerType?: "user" | "organization";
  pauseAt?: "now";
});
```

### useResumeSubscription

Resume a paused subscription.

```tsx theme={null}
import { useResumeSubscription } from "@amank-root/better-auth-razorpay/react";

const resume = useResumeSubscription(authClient);

resume.mutate({
  referenceId?: string;
  customerType?: "user" | "organization";
  resumeAt?: "now";
});
```

### useRestoreSubscription

Restore a subscription that is scheduled to cancel at the end of the current cycle.

```tsx theme={null}
import { useRestoreSubscription } from "@amank-root/better-auth-razorpay/react";

const restore = useRestoreSubscription(authClient);

restore.mutate({
  referenceId?: string;
  customerType?: "user" | "organization";
});
```

### useUpdateSubscription

Update an existing subscription with a new plan, offer, quantity, or metadata.

```tsx theme={null}
import { useUpdateSubscription } from "@amank-root/better-auth-razorpay/react";

const update = useUpdateSubscription(authClient);

update.mutate({
  referenceId?: string;
  customerType?: "user" | "organization";
  planId?: "plan_XXXX";
  offerId?: "offer_XXXX";
  quantity?: 5;
  remainingCount?: 3;
  startAt?: 1893456000;
  scheduleChangeAt?: "now" | "cycle_end";
  customerNotify?: true;
  metadata?: { note: "migrated plan" };
});
```

## 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.

```tsx app/billing/page.tsx theme={null}
"use client";

import { authClient } from "@/lib/auth-client";
import {
  useSubscriptionList,
  useRazorpayPlans,
  useCancelSubscription,
  useResumeSubscription,
  useRestoreSubscription,
  useUpgradeSubscription,
  useSubscriptionStatus,
} from "@amank-root/better-auth-razorpay/react";

export default function BillingSettings() {
  const { data: subscriptions, isLoading: subsLoading } = useSubscriptionList(authClient);
  const { data: plans, isLoading: plansLoading } = useRazorpayPlans(authClient);

  const cancel = useCancelSubscription(authClient);
  const resume = useResumeSubscription(authClient);
  const restore = useRestoreSubscription(authClient);
  const upgrade = useUpgradeSubscription(authClient);

  const activeSub = subscriptions?.[0];
  const status = useSubscriptionStatus(activeSub);

  if (subsLoading || plansLoading) return <p>Loading...</p>;

  return (
    <div style={{ maxWidth: 640 }}>
      <h1>Billing</h1>

      {activeSub ? (
        <div style={{ border: "1px solid rgba(127,127,127,.25)", borderRadius: 12, padding: 16, marginBottom: 24 }}>
          <h2>Current plan: {activeSub.plan}</h2>
          <p>Status: {activeSub.status}</p>
          <p>Period: {activeSub.currentStart} – {activeSub.currentEnd}</p>
          <p>Seats: {activeSub.quantity}</p>

          {status.isTrialing && <p style={{ color: "#16a34a" }}>In free trial</p>}
          {status.hasPaymentIssue && <p style={{ color: "#dc2626" }}>Payment issue detected</p>}

          <div style={{ display: "flex", gap: 8, marginTop: 12 }}>
            {status.isActive && !status.isPaused && (
              <button
                onClick={() => cancel.mutate({ cancelAtCycleEnd: true })}
                disabled={cancel.isPending}
              >
                {cancel.isPending ? "Cancelling..." : "Cancel at cycle end"}
              </button>
            )}

            {status.canRestore && (
              <button
                onClick={() => restore.mutate({})}
                disabled={restore.isPending}
              >
                {restore.isPending ? "Restoring..." : "Restore subscription"}
              </button>
            )}

            {status.isPaused && (
              <button
                onClick={() => resume.mutate({})}
                disabled={resume.isPending}
              >
                {resume.isPending ? "Resuming..." : "Resume"}
              </button>
            )}
          </div>
        </div>
      ) : (
        <p>No active subscription.</p>
      )}

      <h2>Available plans</h2>
      <ul>
        {plans?.items?.map((plan) => (
          <li key={plan.id} style={{ marginBottom: 12 }}>
            <div>{plan.item?.name} — {plan.item?.amount / 100} {plan.item?.currency}</div>
            <button
              onClick={() =>
                upgrade.mutate({ plan: plan.item?.name?.toLowerCase() || "" })
              }
              disabled={upgrade.isPending}
            >
              {upgrade.isPending ? "Upgrading..." : "Upgrade"}
            </button>
          </li>
        ))}
      </ul>
    </div>
  );
}
```

> [!NOTE]
>
> The `useSubscriptionStatus` helper is documented on the [Subscription status](https://better-auth-razorpay.amankushwaha.dev/react/subscription-status.md) page. It returns boolean flags you can use to gate UI without duplicating status logic.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.