sincecutoff.com
/v1/json /v1/md llms.txt
← all changes

Stripe API adds configurable trial offers for subscription items

Introduced 2026-03-25 · score 0.97

HOW TO USE IT

When setting up trial pricing and duration for a subscription item, create a Trial Offer, then attach it through `current_trial`; use `trial_settings.end_behavior.billing_cycle_anchor` to choose the anchor behavior at trial end.

curl https://api.stripe.com/v1/product_catalog/trial_offers -u "<YOUR_SECRET_KEY>" -H "Stripe-Version: 2026-03-25.preview" -d "duration[relative][iterations]=2" -d "end_behavior[transition][price]=<POST_TRIAL_PRICE_ID>" -d price=<TRIAL_PRICE_ID>
curl https://api.stripe.com/v1/subscription_items -u "<YOUR_SECRET_KEY>" -H "Stripe-Version: 2026-03-25.preview" -d subscription=<SUBSCRIPTION_ID> -d price=<PRICE_ID> -d "current_trial[trial_offer]=<TRIAL_OFFER_ID>"
curl https://api.stripe.com/v1/subscriptions -u "<YOUR_SECRET_KEY>" -H "Stripe-Version: 2026-03-25.preview" -d customer=<CUSTOMER_ID> -d "items[0][price]=<PRICE_ID>" -d "trial_settings[end_behavior][billing_cycle_anchor]=now"

WHY THIS HELPS

Configure trial pricing and duration for a subscription item, and set its post-trial billing-cycle behavior.

REQUIREMENTS AND LIMITATIONS

  • Availability: API links specify api-version=2026-03-25.preview.
  • duration (required): Trial duration object; the create example uses `relative[iterations]`.
  • duration[relative][iterations]: Number of price intervals in the documented relative-duration example.
  • end_behavior (required): Defines what occurs when the trial ends; the example transitions to a price.
  • end_behavior[transition][price]: Price used after the trial in the documented transition example.
  • price (required): Price configuration during the trial period.
  • subscription (required): Identifier of the subscription to modify when creating a subscription item.
  • current_trial: Trial Offer to apply to the subscription item.
  • current_trial[trial_offer]: Trial Offer identifier; attachment field shown in the Trial Offer reference.
  • trial_settings.end_behavior.billing_cycle_anchor: Controls whether the subscription billing cycle anchor resets at trial end; permitted values were not exposed in the retrieved reference text.
  • customer: Identifier of the customer to subscribe.
  • items[0][price]: Price ID for a subscription item in the create-subscription example.
  • Prerequisite: Create a Price before creating a Trial Offer; the create reference's prerequisite uses a recurring monthly price.
  • Prerequisite: The Subscription Item create reference lists a PaymentMethod, Customer with attached payment method, Product, Price, and Subscription as prerequisite objects.

FIRST-PARTY EVIDENCE

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

Report a problem with this card