Skip to main content
The subscription option in the Razorpay plugin controls whether subscriptions are enabled and how plans are defined. This page covers every field inside SubscriptionOptions and RazorpayPlan, how to load plans dynamically, and how to use limits, groups, and callbacks.

Subscription options

boolean
required
Set to true to register subscription endpoints and create the local subscription table. Set to false to disable subscriptions entirely.
RazorpayPlan[] | (() => RazorpayPlan[] | Promise<RazorpayPlan[]>)
A static array of plans, or an async function that returns plans at runtime. Use a function when you store plan definitions in your own database or CMS. If the function throws, the plugin raises FAILED_TO_FETCH_PLANS.
boolean
default:"false"
When true, users must verify their email before upgrading. If unverified, the upgrade endpoint returns EMAIL_VERIFICATION_REQUIRED or FORBIDDEN.
({ user, session, referenceId, action }, ctx) => boolean | Promise<boolean>
required
Authorize subscription actions for a specific reference id. The action argument is one of upgrade-subscription, list-subscription, cancel-subscription, pause-subscription, resume-subscription, update-subscription, restore-subscription, or get-subscription. Required for organization subscriptions; without it the plugin raises AUTHORIZE_REFERENCE_REQUIRED. Returning false raises UNAUTHORIZED or REFERENCE_ID_NOT_ALLOWED.
({ user, session, plan }, ctx) => Partial<subscription create params>
Merge extra fields into the Razorpay subscription create payload. Common uses include adding notes, an offer_id, or custom metadata that Razorpay will echo back in webhooks.

Razorpay plan fields

string
required
The Razorpay plan id, for example plan_XXXX. This is the plan that Razorpay bills against.
string
required
The display name matched case-insensitively during upgrades. The matched name is stored in the local subscription row in lowercase, for example pro.
string
An optional Razorpay plan id used when the user selects annual billing during upgrade. If omitted, annual upgrades fall back to planId.
Record<string, unknown>
Arbitrary key-value pairs you can read in your application to gate features. For example, { projects: 5, storageGb: 10 }.
string
A group identifier for categorizing plans, such as individual or team.
number
default:"0"
Number of billing cycles before the subscription automatically completes. 0 means no fixed limit.
number
default:"1"
Default quantity for the subscription. For seat-based plans, this is typically overridden per organization based on member count.
{ days: number, onTrialStart?, onTrialEnd?, onTrialExpired? }
Configure a free trial for this plan. days is the trial length. onTrialStart runs when the trial begins. onTrialEnd runs when the trial ends normally. onTrialExpired runs if the trial expires without activation.

Static vs dynamic plans

You can define plans directly in code, or load them from an external source.

Static plans

Pass a plain array when your plans rarely change:
auth.ts

Dynamic plans

Pass an async function when you manage plans in a database or CMS:
auth.ts
If the function throws, the plugin responds with FAILED_TO_FETCH_PLANS.

Annual plans

When a user upgrades with annual: true, the plugin swaps planId for annualPlanId in the Razorpay subscription create call. If annualPlanId is absent, it falls back to the monthly planId.
client.ts

Using limits to gate features

Store feature limits on each plan, then read them by the stored subscription plan name:
server.ts
Keep a local cache of plan definitions if you query them on every request, or store denormalized limits on the subscription row after upgrade.

Groups, total count, and quantity

  • group lets you render plan selectors in your UI by category.
  • totalCount sets a fixed number of billing cycles. When reached, the subscription status becomes completed.
  • quantity is the default number of units billed per cycle. For seat-based plans, the plugin can override this automatically based on organization membership.

Free trials

A trial delays the first charge by the specified number of days. The plugin records trialStart and trialEnd on the local subscription row. Trials are only granted if the reference id has never had a trial before.
auth.ts
For a complete guide on free trials, including how they interact with upgrades and cancellations, read free trials.

Lifecycle callbacks

Subscription webhooks update the local row automatically, but you can hook into specific transitions for side effects such as provisioning features or sending emails.
({ event, razorpaySubscription, subscription, plan }) => void | Promise<void>
Fired when a subscription becomes active.
({ event, razorpaySubscription, subscription }) => void | Promise<void>
Fired on each successful charge.
({ event, razorpaySubscription, subscription }) => void | Promise<void>
Fired when the subscription is authenticated.
({ event, razorpaySubscription, subscription }) => void | Promise<void>
Fired when the subscription is cancelled.
({ event, razorpaySubscription, subscription }) => void | Promise<void>
Fired when the subscription is paused.
({ event, razorpaySubscription, subscription }) => void | Promise<void>
Fired when the subscription resumes.
({ event, razorpaySubscription, subscription }) => void | Promise<void>
Fired when the subscription is halted.
({ event, razorpaySubscription, subscription }) => void | Promise<void>
Fired when the subscription enters a pending state.
({ event, razorpaySubscription, subscription }) => void | Promise<void>
Fired when the subscription completes all billing cycles.
({ event, razorpaySubscription, subscription }) => void | Promise<void>
Fired when the subscription is updated.
({ event, razorpaySubscription, subscription }) => void | Promise<void>
Fired when the subscription renews.

Example: sending emails on activation

auth.ts
The README shows some subscription callbacks at the top level of the plugin options, but the TypeScript types define them inside subscription. The types are authoritative, so always place callbacks under subscription.