Skip to main content
The better-auth-razorpay plugin supports time-limited free trials on subscription plans. When a trial is configured, the plugin delays the first charge by setting Razorpay’s 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

Add freeTrial to any plan in the plugin’s subscription.plans array.
auth.ts
number
required
Number of days the trial lasts. The plugin computes start_at = now + days and passes it to Razorpay when creating the subscription.
function
Called when the trial begins, after the subscription is created and the local row is stored.
function
Called when the trial period ends and the first charge is attempted.
function
Called if the trial expires without the customer converting to a paid subscription.

How trial start is computed

When a user upgrades to a plan that has freeTrial.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:
  1. Creates the local subscription row with status "created".
  2. Computes start_at as the current Unix timestamp plus freeTrial.days * 86400 seconds.
  3. Sends start_at to Razorpay in the subscription create request.
  4. Stores trialStart on the local row when the subscription.authenticated or 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

Use useSubscriptionStatus 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
isTrialing is a client-side helper based on the local row. It does not guarantee that Razorpay has not already attempted the first charge if the trial period elapsed while the user was offline. Always verify the latest status from webhooks or refetch queries before making entitlement decisions on the server.

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 to active 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 per referenceId (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.

Common errors