Stripe trials: legacy trial_end vs the new Trial Offer API

TL;DR

If no payment method is attached, the first invoice fails and the subscription goes past due. - Use legacy trials with Checkout, Payment Links, and Elements-based flows.

When to use

You are seeing this: Stripe has two trial systems right now, and they do not mix. Use this skill when you run into "Stripe trials: legacy trial_end vs the new Trial Offer API".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

Stripe trials: know which trial system you are on

Stripe has two trial systems right now, and they do not mix. Using the wrong one for your integration surface is the main failure mode.

Legacy trials (trial_end)

• Set trial_period_days or trial_end when creating the subscription. No charge during the trial; usage on metered items is still recorded.
• Listen for customer.subscription.trial_will_end to warn the customer before conversion. It fires a few days before the trial ends.
• At trial end the subscription converts to paid automatically. If no payment method is attached, the first invoice fails and the subscription goes past due.
• Use legacy trials with Checkout, Payment Links, and Elements-based flows.

Trial Offer API (preview)

• A separate object that attaches a discounted or free price to a subscription item for a limited duration, without changing the item's underlying price. Enables paid trials (for example 1 USD for the first week), discounted trials, upgrade trials, and item-level trials.
• Requires the 2026-03-25.preview API version header and subscriptions created with billing_mode set to flexible.
• You need two Price objects: one for the trial period, one for post-trial.
• Cannot be combined with the legacy trial_end parameter. Not supported in Checkout, Payment Links, or subscription schedules in the Dashboard; manage schedules via the API.

Rules

1. Check the API version and billing mode before choosing. If the integration is not on the preview version with flexible billing, legacy trials are the only option.
2. Never set both a trial offer and trial_end on the same subscription.
3. Trial length cannot be changed after the subscription is created, and trial extensions or reductions cannot be scheduled. Get the duration right at creation.
4. For trial-to-paid conversion flows, the critical webhook is trial_will_end on legacy, and the trial offer's end behavior on the new API. Handle both if you support both systems.

Stripe's trial offers doc (public preview) requires API version 2026-03-25.preview and flexible billing mode, two Price objects, and states trial offers cannot be combined with legacy trialend and are unsupported in Checkout/Payment Links. The legacy trial behavior (trialwill_end event, no charge during trial) is documented billing behavior. Verified against live docs 2026-09-26.