start_at to the current time plus the trial duration. Trials are limited to one per reference (user or organization).
Configure a trial on a plan
AddfreeTrial to any plan in the plugin’s subscription.plans array.
auth.ts
Number of days the trial lasts. The plugin computes
start_at = now + days and passes it to Razorpay when creating the subscription.Called when the trial begins, after the subscription is created and the local row is stored.
How trial start is computed
When a user upgrades to a plan that hasfreeTrial.days, the plugin checks whether any previous subscription for the same referenceId already had a trialStart value. If a trial was already used, the subscription starts immediately and TRIAL_ALREADY_USED is not thrown (the trial is simply skipped).
If this is the first trial for that reference, the plugin:
- Creates the local subscription row with status
"created". - Computes
start_atas the current Unix timestamp plusfreeTrial.days * 86400seconds. - Sends
start_atto Razorpay in the subscription create request. - Stores
trialStarton the local row when thesubscription.authenticatedor activation webhook arrives.
Razorpay begins billing from
start_at. Until that time, the customer can use the subscription without being charged.Trial status in React
UseuseSubscriptionStatus to check whether the current subscription is in a trial state. isTrialing returns true when the subscription status is authenticated and trialStart is set while trialEnd is still null.
components/trial-banner.tsx
Trial lifecycle callbacks
The callbacks run on the server and receive the local subscription object.onTrialStart
Fires immediately after the subscription is created with a trial. Use it to provision trial features or send a welcome email.auth.ts
onTrialEnd
Fires when the trial period ends and Razorpay attempts the first charge. The subscription may transition toactive or halted depending on whether the charge succeeds.
auth.ts
onTrialExpired
Fires if the trial expires without conversion. This typically happens when the customer never completes the authorization flow or the first charge fails repeatedly.auth.ts
One trial per reference
The plugin enforces a single trial perreferenceId (user ID or organization ID). If a user cancels their trial subscription and later upgrades to the same plan again, they will not receive a second trial. This prevents repeated trial abuse without requiring you to track trial usage manually.
If you need to reset trial eligibility for a specific customer, delete the old subscription rows from your database or create a new Razorpay customer for that reference.