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
Set to
true to register subscription endpoints and create the local subscription table. Set to false to disable subscriptions entirely.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.When
true, users must verify their email before upgrading. If unverified, the upgrade endpoint returns EMAIL_VERIFICATION_REQUIRED or FORBIDDEN.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.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
The Razorpay plan id, for example
plan_XXXX. This is the plan that Razorpay bills against.The display name matched case-insensitively during upgrades. The matched name is stored in the local subscription row in lowercase, for example
pro.An optional Razorpay plan id used when the user selects annual billing during upgrade. If omitted, annual upgrades fall back to
planId.Arbitrary key-value pairs you can read in your application to gate features. For example,
{ projects: 5, storageGb: 10 }.Number of billing cycles before the subscription automatically completes.
0 means no fixed limit.Default quantity for the subscription. For seat-based plans, this is typically overridden per organization based on member count.
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
FAILED_TO_FETCH_PLANS.
Annual plans
When a user upgrades withannual: 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
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 recordstrialStart and trialEnd on the local subscription row. Trials are only granted if the reference id has never had a trial before.
auth.ts
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.Fired when a subscription becomes active.
Fired on each successful charge.
Fired when the subscription is authenticated.
Fired when the subscription is cancelled.
Fired when the subscription is paused.
Fired when the subscription resumes.
Fired when the subscription is halted.
Fired when the subscription enters a pending state.
Fired when the subscription completes all billing cycles.
Fired when the subscription is updated.
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.