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

# React hooks overview

> Set up TanStack Query and the Better Auth Razorpay React hooks in your client application.

The `@amank-root/better-auth-razorpay/react` package exposes TanStack Query hooks for subscriptions, payments, orders, refunds, invoices, and more. Every hook expects an `authClient` created with the Razorpay client plugin, and they all run inside a `QueryClientProvider`.

## Install peer dependencies

The React hooks require `@tanstack/react-query` and `react` as peer dependencies. Install them alongside the plugin if you haven't already.

> [tab] npm
>
> ```bash theme={null}
> npm install @tanstack/react-query react
> ```

> [tab] yarn
>
> ```bash theme={null}
> yarn add @tanstack/react-query react
> ```

> [tab] pnpm
>
> ```bash theme={null}
> pnpm add @tanstack/react-query react
> ```

> [tab] bun
>
> ```bash theme={null}
> bun add @tanstack/react-query react
> ```

## Wrap your app with QueryClientProvider

Create a `QueryClient` and wrap your application tree so hooks can cache and invalidate data.

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

import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import { useState } from "react";

export function Providers({ children }: { children: React.ReactNode }) {
  const [queryClient] = useState(() => new QueryClient());
  return (
    <QueryClientProvider client={queryClient}>
      {children}
    </QueryClientProvider>
  );
}
```

```tsx app/layout.tsx theme={null}
import { Providers } from "./providers";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <Providers>{children}</Providers>
      </body>
    </html>
  );
}
```

## Pass the auth client to every hook

All hooks take your `authClient` as the first argument. Create it with the Razorpay client plugin and pass it through your app, or import it from a shared module.

```ts lib/auth-client.ts theme={null}
import { createAuthClient } from "better-auth/react";
import { razorpayClient } from "@amank-root/better-auth-razorpay/client";

export const authClient = createAuthClient({
  plugins: [
    razorpayClient({ subscription: true }),
  ],
});
```

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

import { authClient } from "@/lib/auth-client";
import { useSubscriptionList } from "@amank-root/better-auth-razorpay/react";

export function Billing() {
  const { data, isLoading, error } = useSubscriptionList(authClient);

  if (isLoading) return <p>Loading subscriptions...</p>;
  if (error) return <p>Error: {error.message}</p>;

  return (
    <ul>
      {data?.map((sub) => (
        <li key={sub.id}>{sub.plan} — {sub.status}</li>
      ))}
    </ul>
  );
}
```

## Query and mutation options

Query hooks accept an `options` object that can include `queryOptions` for TanStack Query's `useQuery`. Mutation hooks accept `mutationOptions` for `useMutation`. You can set `staleTime`, `refetchInterval`, `onSuccess`, `onError`, and any other standard TanStack Query option.

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

function SubscriptionManager() {
  const { data } = useSubscriptionList(authClient, {
    queryOptions: { staleTime: 60_000, refetchInterval: 30_000 },
  });

  const cancel = useCancelSubscription(authClient, {
    mutationOptions: {
      onSuccess: () => alert("Subscription cancelled"),
      onError: (err) => alert(err.message),
    },
  });

  return (
    <button onClick={() => cancel.mutate({})} disabled={cancel.isPending}>
      {cancel.isPending ? "Cancelling..." : "Cancel subscription"}
    </button>
  );
}
```

## Query keys

The package exports `razorpayQueryKeys` so you can invalidate or prefetch data manually.

| Key factory | Arguments | Use with |
| - | - | - |
| `razorpayQueryKeys.all` | none | `invalidateQueries({ queryKey: razorpayQueryKeys.all })` |
| `razorpayQueryKeys.subscriptions()` | none | `useSubscriptionList` cache |
| `razorpayQueryKeys.subscriptionList(referenceId?, customerType?)` | `referenceId`, `customerType` | `useSubscriptionList` with filters |
| `razorpayQueryKeys.subscription(id)` | `subscriptionId` | `useSubscription` |
| `razorpayQueryKeys.razorpaySubscription(id)` | `razorpaySubscriptionId` | `useRazorpaySubscription` |
| `razorpayQueryKeys.allSubscriptions(query?)` | `query` | `useRazorpaySubscriptions` |
| `razorpayQueryKeys.subscriptionInvoices(id)` | `subscriptionId` | `useRazorpayInvoices` |
| `razorpayQueryKeys.pendingUpdate(id)` | `subscriptionId` | `useSubscriptionPendingUpdate` |
| `razorpayQueryKeys.plans()` | none | `useRazorpayPlans` |
| `razorpayQueryKeys.plan(id)` | `planId` | Plan detail cache |
| `razorpayQueryKeys.payments()` | none | `useRazorpayPaymentList` |
| `razorpayQueryKeys.payment(id)` | `paymentId` | `useRazorpayPayment` |
| `razorpayQueryKeys.refunds()` | none | `useRazorpayRefundList` |
| `razorpayQueryKeys.refund(id)` | `refundId` | `useRazorpayRefund` |
| `razorpayQueryKeys.orders()` | none | `useRazorpayOrderList` |
| `razorpayQueryKeys.invoices()` | none | `useRazorpayInvoiceList` |
| `razorpayQueryKeys.invoice(id)` | `invoiceId` | `useRazorpayInvoice` |
| `razorpayQueryKeys.addons()` | none | `useRazorpayAddonList` |
| `razorpayQueryKeys.addon(id)` | `addonId` | `useRazorpayAddon` |
| `razorpayQueryKeys.items()` | none | `useRazorpayItemList` |
| `razorpayQueryKeys.item(id)` | `itemId` | `useRazorpayItem` |
| `razorpayQueryKeys.customers()` | none | Customer list cache |
| `razorpayQueryKeys.customer(id)` | `customerId` | Customer detail cache |
| `razorpayQueryKeys.tokens(customerId)` | `customerId` | `useRazorpayCustomerTokens` |
| `razorpayQueryKeys.bankAccounts(customerId)` | `customerId` | Bank account cache |
| `razorpayQueryKeys.transfers()` | none | `useRazorpayTransferList` |
| `razorpayQueryKeys.transfer(id)` | `transferId` | `useRazorpayTransfer` |

### Invalidation example

After a successful mutation, invalidate related queries so the UI refreshes automatically.

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

function CancelButton() {
  const queryClient = useQueryClient();
  const cancel = useCancelSubscription(authClient, {
    mutationOptions: {
      onSuccess: () => {
        queryClient.invalidateQueries({ queryKey: razorpayQueryKeys.subscriptions() });
        queryClient.invalidateQueries({ queryKey: razorpayQueryKeys.plans() });
      },
    },
  });

  return (
    <button onClick={() => cancel.mutate({})} disabled={cancel.isPending}>
      Cancel
    </button>
  );
}
```

> [!NOTE]
>
> All hooks are client-only. In Next.js App Router, add `"use client"` at the top of any file that imports from `@amank-root/better-auth-razorpay/react`. If you need server-rendered data, fetch it in a Server Component and pass it down as props.


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