Sample - Stripe API
POST/v1/subscription_schedules/{schedule}/release

Release a subscription schedule

Releases a subscription schedule immediately and stops the schedule from applying future phases. The associated subscription remains in place, and its identifier moves to released_subscription when the schedule is currently associated with one. You can release only a schedule whose status is not_started or active.

  • RetriesRetries up to 2×, 500ms backoff, 30s timeout.
  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

1 parameter · 2 body fields
schedulestringrequired
The unique identifier of the subscription schedule to release. Must be no longer than 5000 characters.

Optional settings for releasing the schedule and expanding the response.

expandarray<string>optional
Specifies which fields in the response should be expanded.
preserve_cancel_datebooleanoptional
Keep any cancellation on the subscription that the schedule has set

2 status codes
200Returns the released subscription schedule, including its updated status and the released subscription relationship when applicable.
applicationstringoptional
ID of the Connect Application that created the schedule.
billing_modeobjectrequired
The billing mode of the subscription.
canceled_atintegeroptional
Time at which the subscription schedule was canceled. Measured in seconds since the Unix epoch.
completed_atintegeroptional
Time at which the subscription schedule was completed. Measured in seconds since the Unix epoch.
createdintegerrequired
Time at which the object was created. Measured in seconds since the Unix epoch.
current_phaseobjectoptional
Object representing the start and end dates for the current phase of the subscription schedule, if it is `active`.
customerstringrequired
ID of the customer who owns the subscription schedule.
customer_accountstringoptional
ID of the account who owns the subscription schedule.
default_settingsobjectrequired
end_behaviorstringrequired
Behavior of the subscription schedule and underlying subscription when it ends. Possible values are `release` or `cancel` with the default being `release`. `release` will end the subscription schedule and keep the underlying subscription running. `cancel` will end the subscription schedule and cancel the underlying subscription.
Allowed:cancelnonereleaserenew
idstringrequired
Unique identifier for the object.
livemodebooleanrequired
If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`.
metadataobjectoptional
Set of [key-value pairs](https://docs.stripe.com/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
objectstringrequired
String representing the object's type. Objects of the same type share the same value.
Allowed:subscription_schedule
phasesarray<SubscriptionSchedulePhaseConfiguration>required
Configuration for the subscription schedule's phases.
released_atintegeroptional
Time at which the subscription schedule was released. Measured in seconds since the Unix epoch.
released_subscriptionstringoptional
ID of the subscription once managed by the subscription schedule (if it is released).
statusstringrequired
The present status of the subscription schedule. Possible values are `not_started`, `active`, `completed`, `released`, and `canceled`. You can read more about the different states in our [behavior guide](https://docs.stripe.com/billing/subscriptions/subscription-schedules).
Allowed:activecanceledcompletednot_startedreleased
subscriptionstringoptional
ID of the subscription managed by the subscription schedule.
test_clockstringoptional
ID of the test clock this subscription schedule belongs to.
defaultError response.
errorobjectrequired

Error handling

schedule must identify a subscription schedule whose status is not_started or active. preserve_cancel_date controls whether a cancellation already set on the subscription is retained. Each value in expand must be a field name no longer than 5000 characters.