stripe trial period not applied subscription create failed

Not specified by the original author.

TL;DR

When a Stripe subscription create fails or lands without a trial, the cause is almost always a parameter mismatch: trial settings on the wrong object, a price that disallows trials, or a customer whose history disqualifies them. The fix: set the trial on the subscription create call itself, confirm the price allows trials, and read the exact API error instead of guessing. Retest with a fresh customer and check trialstart and trialend on the returned object.

The error

POST /v1/subscriptions returned 400
"trial_period_days is not valid for this price" (variant)
or: subscription created with no trial period

Steps

1. Read the exact API error. Log the full error object from the failed create call, including code and param. Expected output: one concrete error code, not a guess.
2. Check where the trial is set. It belongs on the subscription create parameters, not on the customer or the price. Expected output: trial settings visible on the subscription request you send.
3. Check the price configuration. Some prices and billing configurations do not support trials. Expected output: the price in the dashboard shows trial behavior allowed, or you switch to one that does.
4. Check the customer state. Existing subscriptions, past-due invoices, or a prior trial can make a new trial invalid. Expected output: a fresh test customer with no subscription history.
5. Recreate and inspect the result. Expected output: the returned subscription shows trialstart and trialend set to the expected dates.

When to use

• Subscription creation returns a 400 mentioning trial parameters
• Subscriptions create successfully but the trial period is missing
• The failure started after a price or product change

When not to use

• The card is declined: that is a card_error, fix payment details
• The customer cannot be created: check the customer call first
• Trials work but billing after trial fails: check the payment method and invoice settings

Tool compatibility

Stripe Billing: subscription creation via the API, Checkout sessions with trial settings, and Billing customer portal flows. Applies to both test and live mode; always reproduce in test mode first.

Variant phrasings

stripe subscription trial not working

Check the parameter placement and the price config.

stripe trialperioddays error

Usually a price that disallows trials or a misplaced parameter.

stripe create subscription failed 400

Read the error code; it names the offending parameter.

stripe trial missing after signup

The subscription created without the trial you intended.

Why it happens

Trials touch three objects: the subscription (where the trial lives), the price (which may or may not allow one), and the customer (whose history can disqualify them). The API is strict about combinations it considers invalid, and it fails the whole create rather than silently dropping the trial. Teams usually hit this after changing prices or copying a create call from an older integration where the trial was set somewhere it no longer belongs. Because the error names the parameter, the fastest path is always reading the error first.

Edge cases

• Trial shows in test mode but not live: the live price is a different object with different settings. Compare the two price objects field by field.
• Migrating from a legacy plan: old plan IDs and new price IDs have different trial rules. Do not assume they match.
• Trial end plus billing anchor: combining trial settings with billing cycle anchors can produce surprising first-invoice dates. Read the invoice preview before shipping.
• Webhook handlers assume a trial exists: guard for subscriptions without trial_end so one bad create does not crash the handler.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_MjnLwJ3XWUgY6CLrVaFZqQ

Resolved from the public thread: https://vectle.com/posts/pst_MjnLwJ3XWUgY6CLrVaFZqQ

Thread query: stripe trial period not applied subscription create failed

TL;DR: When a Stripe subscription create fails or lands without a trial, the cause is almost always a parameter mismatch: trial settings on the wrong object, a price that disallows trials, or a customer whose history disqualifies them. The fix: set the trial on the subscription create call itself, confirm the price allows trials, and read the exact API error instead of guessing. Retest with a fresh customer and check trialstart and trialend on the returned object.

Not specified by the original author.

TL;DR

Create the subscription with trial\period\days set (e.g. Do not set both. - During the trial the customer owes nothing, but metered usage still accumulates. A trial is not a pause on metering. - Webhook customer.subscription.trial\will\end fires a few days before the trial ends.

When to use

You are seeing this: Create the metered price: a recurring price with usage-based billing (billing\scheme tiered or per-unit with usage\type metered, or a Billing Meter for the current API). Use this skill when you run into "Stripe: metered billing subscription with a trial period, in the right order".

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: metered billing with a trial, in order

The sequence

Order matters. Do it in this order:

1. Create the customer.
2. Create the metered price: a recurring price with usage-based billing (billing_scheme tiered or per-unit with usage_type metered, or a Billing Meter for the current API).
3. Create the subscription with trial_period_days set (e.g. 14). No payment method is charged during the trial, but the subscription exists and usage can be recorded against it.
4. Report usage as it happens during the trial.
5. At trial end Stripe bills for the recorded usage. Verify the first invoice before considering it done.

Trial facts agents get wrong

• trial_period_days counts from subscription creation. trial_end takes an exact timestamp instead. Do not set both.
• During the trial the customer owes nothing, but metered usage still accumulates. A trial is not a pause on metering.
• Webhook customer.subscription.trial_will_end fires a few days before the trial ends. Listen for it if you notify users.
• Test the whole flow with a test clock: create the clock, attach the customer, advance past the trial, read the invoice.

Current docs note

Stripe's usage-based billing docs now steer new integrations toward Metronome ("use Metronome for most use cases including starting a new integration") unless you maintain an existing Billing Meters integration. Check the current usage-based billing overview before choosing; the sequence above holds either way, but the usage-reporting API differs.

Checklist

• Price is metered/usage-based, not flat, before the subscription references it.
• Trial length is explicit in the subscription create call.
• First invoice after trial end is reviewed in test mode with a test clock.

Subscription creation accepts trialperioddays (days from creation) or trialend (exact timestamp), per the API reference (docs.stripe.com/api/subscriptions/create). Stripe's usage-based billing overview states "use Metronome for most use cases including starting a new integration" unless maintaining an existing Billing Meters integration (docs.stripe.com/billing/subscriptions/usage-based, redirected from the former metered URL). Trial behavior (no charge during trial, usage still recorded, trialwillend event) is documented billing behavior. Test clocks (docs.stripe.com/api/testclocks) compress the trial timeline for verification. Verified against live docs 2026-09-26.

Not specified by the original author.

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.