Sample - Stripe API
POST/v1/subscription_schedules

Create a schedule

Creates a new subscription schedule object. Each customer can have up to 500 active or scheduled subscriptions.

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

10 body fields
billing_modeobjectoptional
Controls how prorations and invoices for subscriptions are calculated and orchestrated.
customerstringoptional
The identifier of the customer to create the subscription schedule for.
customer_accountstringoptional
The identifier of the account to create the subscription schedule for.
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.
from_subscriptionstringoptional
Migrate an existing subscription to be managed by a subscription schedule. If this parameter is set, a subscription schedule will be created using the subscription's item(s), set to auto-renew using the subscription's interval. When using this parameter, other parameters (such as phase values) cannot be set. To create a subscription schedule with other modifications, we recommend making two separate API calls.
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.
start_dateintegeroptional
When the subscription schedule starts. We recommend using `now` so that it starts the subscription immediately, and to avoid unexpected behavior due to request delays or clock skew resulting in a slightly backdated or postdated start. You can also use a Unix timestamp to backdate the subscription so that it starts on a past date, or set a future date for the subscription to start on.

2 status codes
200Successful response.
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

Any other status is an error: Error response.