Skip to main content
The better-auth-razorpay plugin provides full subscription management backed by Razorpay. This guide covers enabling subscriptions, defining plans, upgrading users, handling the subscription lifecycle, and gating application features based on plan limits and status.

Enable subscriptions

Set subscription.enabled: true in the plugin options and provide at least one plan. Each plan maps a friendly name to a Razorpay plan_id.
auth.ts
Set createCustomerOnSignUp: true so every user gets a Razorpay customer ID stored in user.razorpayCustomerId. The upgrade endpoint requires it.
After adding the plugin, run Better Auth’s schema migration to create the subscription table:

Upgrade flow

Call authClient.subscription.upgrade from your frontend to create a subscription. The plugin creates a local row with status "created", then creates the Razorpay subscription and returns a shortUrl (hosted authorization page) and a Razorpay subscription_id.
pages/pricing.tsx
The annual: true option swaps the plan to its annualPlanId. If you do not define annualPlanId, the monthly plan is used regardless of this flag.

Subscription lifecycle

A subscription moves through several statuses as the customer authorizes payment, the first charge succeeds, and subsequent billing cycles progress. The plugin keeps the local subscription row in sync via webhooks.
1

Created

The plugin creates a local row and a Razorpay subscription. The customer has not yet authorized payment.
2

Authenticated

The customer completed the Razorpay authorization flow. A trial may be active.
3

Active

The first charge succeeded and recurring billing is in progress.
4

Paused

Billing is temporarily stopped. Resume to return to active.
5

Halted

Razorpay halted the subscription after repeated payment failures. It can be resumed.
6

Cancelled

The subscription was cancelled by the user or admin. It will not bill again.
7

Completed

All billing cycles finished successfully.
8

Expired

The subscription expired without completing all cycles.

Cancel, pause, resume, and restore

Use the client methods or React mutation hooks to manage an existing subscription.

Cancel now or at cycle end

Pause and resume

Restore a pending cancellation

If a subscription has cancelAtCycleEnd: true, you can restore it before the cycle ends:
Restore only clears the local cancelAtCycleEnd flag. Razorpay does not expose a native restore API for subscriptions scheduled to cancel.

Update a subscription

Change the plan, seat quantity, metadata, or schedule a change for the next cycle.
string
Razorpay plan ID to switch to.
number
Number of seats or units.
string
"now" applies immediately. "cycle_end" applies after the current period.
object
Arbitrary key-value data stored on the subscription.

List and get subscriptions

Fetch local subscriptions for the current user or an organization.
For organization subscriptions, pass customerType: "organization" and optionally referenceId:

Feature gating with plan limits

Use limits defined in each plan and useSubscriptionStatus to guard features in your UI.
components/feature-gate.tsx
isUsable returns true when the subscription is active or in a usable authenticated/trial state. isTerminal returns true for cancelled, completed, or expired.

Common errors

Webhook activation

Razorpay sends subscription.authenticated, subscription.activated, and subscription.charged events as the subscription progresses. The plugin updates the local row before firing your callbacks. You do not need to poll for status changes if webhooks are configured.
auth.ts
See Webhooks for full setup instructions.