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

Cancel a subscription schedule

Cancels a subscription schedule and its associated active subscription immediately when applicable. You can cancel only a schedule whose status is not_started or active, and you can control final invoicing and proration for an active schedule. A successful response contains the canceled schedule and its updated lifecycle fields.

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

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

Optional cancellation settings for final invoicing, proration, and response expansion.

expandarray<string>optional
Specifies which fields in the response should be expanded.
invoice_nowbooleanoptional
If the subscription schedule is `active`, indicates if a final invoice will be generated that contains any un-invoiced metered usage and new/pending proration invoice items. Defaults to `true`.
proratebooleanoptional
If the subscription schedule is `active`, indicates if the cancellation should be prorated. Defaults to `true`.

2 status codes
200Returns the canceled subscription schedule, including its updated status, cancellation time, subscription details, phases, and end behavior.
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. invoice_now and prorate apply to active schedules and default to true when omitted. Each value in expand must be a field name no longer than 5000 characters.