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

Get a subscription schedule

Retrieves the details of a specific subscription schedule. Supply the schedule identifier returned when the schedule was created and optionally expand fields in the response. Use this endpoint when you need the schedule's phases, status, customer, or lifecycle timestamps.

  • RetriesRetries up to 2×, 500ms backoff, 30s timeout.

2 parameters
schedulestringrequired
The unique identifier of the subscription schedule to retrieve. Must be no longer than 5000 characters.
expandarray<string>optional
Fields to expand in the response. Each field name must be no longer than 5000 characters.

2 status codes
200Returns the subscription schedule, including its identifier, customer, billing mode, default settings, phases, status, lifecycle timestamps, 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 to retrieve and must be no longer than 5000 characters. Each value in expand must be a field name no longer than 5000 characters.