Skip to main content
In this guide you’ll add a free trial to a product, start a trialing subscription, and manage the trial (extend or end it) on an existing subscription. A trial lets a customer use your product before the first charge: their card is saved at checkout, but nothing is billed until the trial ends.
Trials are in beta. The behavior below might change.

​
Before you start

​
Steps

1

Add a trial to the product

A trial is a property of the product: a trial_period duration alongside the recurring billing_cycle. Set it when you create the product.
Create a product with a 14-day trial
trial_period is a duration: { "interval": "day", "frequency": 14 } is 14 days. It’s only meaningful on a recurring product (one with a billing_cycle); it does nothing on a one-time product.
2

Start the trial (check the customer out)

There’s no separate trial call. When a customer completes a checkout for a product that has a trial_period, Bachs saves their card without charging it, creates the subscription in trialing, and schedules the first charge for the end of the trial.
Subscription created in trial
When the trial ends, Bachs bills the first cycle off-session using the saved card, the subscription moves to active, and normal renewals begin. If the customer cancels before the trial ends, they’re never charged.
3

Extend or end a trial (optional)

Manage a trial on an existing subscription through a single field, trial_end, on Update a subscription. A trial change stands alone; don’t combine it with other changes in the same request.
  • A future trial_end extends (or starts) the trial and postpones billing. This works even on an active subscription, which becomes trialing.
  • A trial_end of now or the past ends the trial immediately: the subscription becomes active, a fresh billing cycle starts, and Bachs charges the first cycle right away.
Ending a trial is only valid while the subscription is trialing. Sending a past trial_end on a subscription that isn’t trialing returns 400.

​
What you’ll receive

  • Trial started: customer.subscription.created with status: "trialing".
  • Trial added, extended, or ended: customer.subscription.updated.
  • Trial ends and the first cycle is billed: invoice.paid, or invoice.payment_failed if the saved card fails (which starts payment recovery).
Treat these webhooks as the source of truth for granting and revoking access. See Set up webhooks.

​
Next steps