Trial Offers support archiving and trial end settings

Introduced 2026-09-30 · score 0.91

HOW TO USE IT

To retire a trial offer, set `active=false` when creating or updating it. For subscription trial-end behavior, set `trial_settings` to configure the missing-payment-method action and billing-cycle anchor.

curl https://api.stripe.com/v1/product_catalog/trial_offers/<TRIAL_OFFER_ID> \
  -u "<YOUR_SECRET_KEY>" \
  -H "Stripe-Version: 2026-09-30.preview" \
  -d active=false

curl https://api.stripe.com/v1/subscriptions \
  -u "<YOUR_SECRET_KEY>" \
  -H "Stripe-Version: 2026-09-30.preview" \
  -d customer=<CUSTOMER_ID> \
  -d "items[0][price]=<PRICE_ID>" \
  -d "trial_settings[end_behavior][missing_payment_method]=pause" \
  -d "trial_settings[end_behavior][billing_cycle_anchor]=unchanged"

WHY THIS HELPS

Retire an outdated trial offer while preserving subscriptions already using it, or configure what happens when a trial ends.

BEFORE THIS CHANGE

For missing-payment-method behavior, use subscription-level free trials; trial offers did not support those options. The source doesn't state the prior archiving behavior or prior billing cycle anchor behavior.

REQUIREMENTS AND LIMITATIONS

active: Boolean; whether the trial offer can be used for new purchases. Set to `false` to archive it.
trial_settings.end_behavior.missing_payment_method: At trial end without a payment method, choose `create_invoice`, `pause`, or `cancel`.
trial_settings.end_behavior.billing_cycle_anchor: The release note describes `unchanged` as preserving the existing billing cycle and creating a prorated post-trial period.
end_behavior.type: Use this property to determine the trial offer’s end behavior.
end_behavior.transition: Optional property; it is no longer returned on all responses.
customer: Identifier of the customer to subscribe.
items (required): List of up to 20 subscription items, each with an attached price.
Prerequisite: The subscription-create reference lists prerequisite setup: create a payment method, create a customer and attach it, create a product, and create a price.
Prerequisite: Requests use a Stripe secret key and the `2026-09-30.preview` API version.
Archived offers can't be attached to new subscription items; existing subscriptions continue using the trial offer until their trial ends.
Missing-payment-method settings apply when a trial ends naturally or when the trial is ended early by changing or removing the trialing item.

FIRST-PARTY EVIDENCE

Check the installed version and the source before using it. Entry JSON

Report a problem with this card

Tools change faster than your agent’s training data.

Changes

Trial Offers support archiving and trial end settings