Subscriptions & free trials

Recurring prices and subscription checkouts let you bill customers on a schedule. This guide explains the billing model, how free trials work (including per-customer trials), and how Rollo prevents trial abuse so renewals still collect.

One-time vs recurring

A one-time price creates a single charge when checkout completes. There is no ongoing obligation after that payment. Use one-time prices for downloads, event tickets, setup fees, or any product that should not renew.

A recurring price bills on an interval you choose: day, week, month, or year. Completing a recurring checkout creates a Subscription object. The customer is charged for each billing period until the subscription is canceled or payment fails according to your recovery settings.

Free trials

Free trials are available only on recurring prices. When trial_days is greater than zero, checkout collects customer details and a payment method, then opens a subscription in trialing status. The first period is $0. When the trial ends, Rollo charges the recurring price automatically using the saved payment method.

Live trials always collect a card (or other method) up front even though the initial amount is zero. That is required so the first renewal can succeed without asking the customer again.

One free trial per customer

Each customer email may use a free trial once per merchant workspace (scoped separately in Sandbox and Live). If that email already completed a trial checkout, Rollo automatically removes trial_days from the session and bills the normal recurring price immediately.

Eligibility is re-checked when the buyer enters their email on hosted checkout. Merchants do not need a separate “block trial” API call for the common case: pass trial_days and Rollo enforces the one-trial rule.

Create a trial for a particular customer

Prefer attaching the customer email when you create the session so Rollo can decide trial eligibility before redirect:

POST /v1/checkout_sessions
Authorization: Bearer rk_live_...
Content-Type: application/json

{
  "price": "price_...",
  "mode": "subscription",
  "trial_days": 14,
  "customer_email": "ada@example.com",
  "success_url": "https://example.com/welcome",
  "cancel_url": "https://example.com/pricing"
}

# If ada@example.com never used a trial → session keeps trial_days: 14
# If they already used a trial → trial_days is omitted; first charge is full price

You can also set a default trial on the catalog price (Products → Edit price → Trial days). Payment links and sessions that reference that price inherit the trial, still subject to the one-trial rule per email.

To offer a trial only to a specific buyer without changing the catalog price, create an ad-hoc session with amount + interval + trial_days and that buyer's customer_email:

{
  "amount": 2900,
  "currency": "usd",
  "mode": "subscription",
  "interval": "month",
  "trial_days": 7,
  "customer_email": "vip@example.com",
  "success_url": "https://example.com/welcome"
}

Trial lifecycle & webhooks

  1. Checkout completes with payment method on file → checkout_session.completed, subscription.created (status trialing).
  2. About three days before the trial ends → subscription.trial_will_end.
  3. Trial ends successfully → subscription becomes active, invoice.paid.
  4. Renewal charge fails → invoice.payment_failed and past-due recovery (see Payment recovery).

Recommended integration flow

  1. Create a recurring price (optionally with default trial days) in the dashboard or via API.
  2. Create a checkout session with the price (and customer_email when known). Override trial_days per session when you want a one-off offer.
  3. Redirect to the hosted checkout URL. Copy should say they are starting a free trial that converts to paid billing.
  4. Provision access on subscription.created / invoice.paid. Gate paid-only features after status is active if you want.

Example: subscription checkout (no trial)

POST /v1/checkout_sessions
Authorization: Bearer rk_live_...
Content-Type: application/json

{
  "price": "price_...",
  "mode": "subscription",
  "success_url": "https://example.com/welcome",
  "cancel_url": "https://example.com/pricing"
}

Metrics

The Customers page reports MRR and ARR from active subscriptions, plus projected MRR/ARR that includes trialing subscriptions expected to convert. Treat projected figures as forecasts until trials convert and invoices pay.

Next guides