Stripe Trial Settings

The three values, and what Stripe says each one does

Stripe documents the enum tersely in the API reference and then expands each option in its free trials guide. Both are worth reading, because the guide carries the consequence that the reference leaves out.

cancel is the blunt one. The reference says it will "cancel the subscription if a payment method is not attached when the trial ends", and the guide adds the timing: if the free trial subscription ends without a payment method, it cancels immediately. You can create another subscription later if the customer comes back.

pause is the one people reach for and then misjudge. The reference says it will "pause the subscription if a payment method is not attached when the trial ends". The guide is more useful: the subscription pauses and does not cycle until it is resumed, and while paused it does not generate invoices. Stripe adds that the subscription can remain paused indefinitely, and that when your customer adds a payment method afterwards you can resume the same subscription rather than building a new one.

create_invoice is the one that reaches your books. The reference describes it as creating "an invoice when the trial ends, even if the user did not set up a payment method", and the guide states the consequence plainly: if a payment method is not provided when the invoice finalizes, the subscription moves into past_due. So the ordinary outcome of a no-card trial under this setting is a finalized invoice nobody can pay and a subscription that Stripe now treats as delinquent.

On the question of which one you get by default, be careful. Stripe does not label any of the three a default in the API reference. What it does publish is an example subscription object carrying create_invoice, and a guide that presents cancel and pause as the values you deliberately set, introducing create_invoice as the alternative. That is suggestive rather than documented, so read the value off your own subscriptions instead of assuming it.

Only one of the three leaves anything behind

Set the outcomes side by side and the accounting shape is lopsided.

Under create_invoice, a real invoice finalizes for the full recurring amount, addressed to somebody who has never given you a way to pay it. That invoice is a document, it has a number, and it will sit unpaid while Stripe moves the subscription to past_due. Whatever your books do when an invoice finalizes, they do here.

Under pause, nothing happens. Stripe generates no invoices for a paused subscription, so there is no document to record, no receivable, and no signal. The customer is still there, the subscription still exists, and your books have no idea either is true.

Under cancel, nothing happens either, for a different reason. The subscription is gone, so there is nothing left to generate.

That asymmetry is the practical content of this field. Two of the three options make the end of a trial completely invisible on the accounting side, and the third makes it visible in the least useful way available, as a receivable you are unlikely to ever collect. Neither behaviour is wrong, but they demand different habits. If you run pause or cancel, trial conversion is a question only Stripe can answer, and any report built on invoices will undercount what happened.

This pause is not the other pause

Stripe has two features called pausing, and this field reaches only one of them.

The paused subscription status is documented as unreachable by any other route. Stripe states that a subscription can only enter a paused status when a trial ends without a payment method, that a paused subscription does not generate invoices, and that it can be resumed after your customer adds their payment method. So setting missing_payment_method to pause is not one way to reach the paused status. It is the way.

Pausing payment collection is a different feature entirely, and Stripe draws the contrast itself: the paused status "is different from pausing collection, which still generates invoices and leaves the subscription’s status unchanged". One stops the documents and changes the status. The other keeps the documents coming and changes nothing you would think to check.

One more detail belongs here, because it is where the missing document finally appears. Stripe notes that resuming a subscription might generate an invoice and a corresponding PaymentIntent that must be paid before the subscription moves out of the paused status. A trial that paused in March and resumed in July produces its first invoice in July, on a date nothing in your billing calendar predicted.

Three different Stripe fields are called end_behavior

This is a genuine trap when you go looking, because the name is reused across unrelated objects and each one answers a different question.

The one on this page is trial_settings.end_behavior, whose only documented sub-field is missing_payment_method, and it decides what a trial ending does when no card is attached.

A subscription schedule carries its own end_behavior, documented as the "behavior of the subscription schedule and underlying subscription when it ends", with release the default and cancel the alternative. Stripe says release ends the schedule and keeps the underlying subscription running, while cancel ends the schedule and cancels the subscription with it. That field is about a schedule finishing its phases, not about trials or payment methods.

Stripe’s trial offers feature adds a third, where end_behavior names the price the subscription transitions to once the trial completes. That one is about what you charge next.

None of the three can be reasoned about from the others, so when a colleague says the end behavior is set to cancel, the useful next question is which end_behavior they mean.