Enable subscriptions
Setsubscription.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.subscription table:
Upgrade flow
CallauthClient.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 localsubscription 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 hascancelAtCycleEnd: true, you can restore it before the cycle ends:
Update a subscription
Change the plan, seat quantity, metadata, or schedule a change for the next cycle.List and get subscriptions
Fetch local subscriptions for the current user or an organization.customerType: "organization" and optionally referenceId:
Feature gating with plan limits
Uselimits 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 sendssubscription.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