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

Update a subscription schedule

Updates the default settings, phases, end behavior, metadata, or proration behavior of an existing subscription schedule. Use phases to change the schedule's future billing configuration and end_behavior to control what happens when the schedule ends. The updated schedule response includes its current lifecycle state and complete phase configuration.

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

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

Optional subscription schedule changes covering default settings, phases, metadata, and proration behavior.

default_settingsobjectoptional
Object representing the subscription schedule's default settings.
end_behaviorstringoptional
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
expandarray<string>optional
Specifies which fields in the response should be expanded.
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. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to `metadata`.
phasesarray<PhaseConfigurationParams>optional
List representing phases of the subscription schedule. Each phase can be customized to have different durations, plans, and coupons. If there are multiple phases, the `end_date` of one phase will always equal the `start_date` of the next phase. Note that past phases can be omitted.
proration_behaviorstringoptional
If the update changes the billing configuration (item price, quantity, etc.) of the current phase, indicates how prorations from this change should be handled. The default value is `create_prorations`.
Allowed:always_invoicecreate_prorationsnone

2 status codes
200Returns the updated subscription schedule, including its lifecycle state, default settings, phases, end behavior, customer, and metadata.
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 the subscription schedule and must be no longer than 5000 characters. Enum fields must use the documented values, including end_behavior, proration_behavior, billing_cycle_anchor, and collection_method. Each phase must include items, and nested automatic_tax objects require enabled.