## 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 trial_start and trial_end on the returned object.

## The error
```text
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 trial_start and trial_end 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 trial_period_days 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