Skip to main content

Trial

A trial is a free or reduced-price period at the start of a subscription. You configure it on the plan, and it applies whenever a subscription is created against that plan.

Configuration​

The plan carries a trial block:

trial: {
  price: 0,
  period: {
    unit: 'day', // 'day' | 'week' | 'month' | 'year'
    length: 1,
  }
}
FieldDescription
trial.priceAmount charged during the trial. Usually 0 for a free trial; can be non-zero for a paid trial (for example $1 for the first 7 days).
trial.period.unitUnit of the trial duration: day, week, month, or year.
trial.period.lengthNumber of units.

Trial in the end-to-end flow​

A subscription with a trial behaves like a normal subscription with one difference: the first paid renewal does not run until the trial ends.

  1. The subscription is created (step 5 of the Subscription flow).
  2. The subscription enters the trial period. Billing for the trial price runs at the start — for a $0 trial, that is a $0 invoice.
  3. At the end of the trial, the subscription moves to its first paid renewal. The plan's recurringInterval takes over from there.
  4. The status moves from trial-ended to active once the first paid renewal succeeds.

Trial and the inactive instrument​

If the subscription is created against a new (inactive) payment instrument, the customer still completes the first payment on the hosted payment form — even for a $0 trial. The hosted-form payment runs at the trial price (zero if free) and activates the payment instrument, so the first paid renewal at the end of the trial auto-charges. See Hosted payment form.

Trial-only plans​

Setting isTrialOnly: true on the subscription create request indicates the plan is trial-only — the subscription ends when the trial ends and no paid renewals run. Confirm with your plan definition that this matches the intended product.

Changing plan during a trial​

A mid-trial plan change via the upgrade/downgrade endpoint does not extend the trial. The trial runs to its scheduled end on the new plan, and proration does not apply to the trial period itself. See Upgrade and downgrade.