Stripe: Update a schedule

Stripe subscriptionSchedules.postSubscriptionSchedulesSchedule: arguments, response, policy and SDK examples.

← Subscription schedules operations · Get started

Operation stripe.postsubscriptionschedulesschedule

Provider route: POST /v1/subscription_schedules/{schedule}. Alter supplies the connection’s credentials and routing.

Call through Alter

Install @alter-ai/sdk @alter-ai/stripe with npm, or alter-sdk-stripe with pip. Supply your connected customer’s grant ID and the arguments described below.

import { App } from "@alter-ai/sdk";
import { StripeIntegration } from "@alter-ai/stripe";

async function execute(input: Parameters<StripeIntegration["subscriptionSchedules"]["postSubscriptionSchedulesSchedule"]>[0]) {
  const app = new App({ apiKey: process.env.ALTER_API_KEY! });
  try {
    const provider = new StripeIntegration(app, { grantId: process.env.PROVIDER_GRANT_ID! });
    const call = await provider.subscriptionSchedules.postSubscriptionSchedulesSchedule(input);
    const result = await call.wait();
    return result.bodyJson();
  } finally {
    await app.close();
  }
}

import os
from alter_sdk import App
from alter_sdk_stripe import StripeIntegration

async def execute(arguments):
    async with App(api_key=os.environ["ALTER_API_KEY"]) as app:
        provider = StripeIntegration(app, {"grant_id": os.environ["PROVIDER_GRANT_ID"]})
        call = await provider.subscription_schedules.post_subscription_schedules_schedule(arguments)
        result = await call.wait()
        return result.body_json()

Input

Field	Type	Presence	Description and constraints
`$`	object	Root	Additional keys: not allowed
`path`	object	Required within parent	Additional keys: not allowed
`path.schedule`	string	Required within parent	Maximum length: 5000
`headers`	object	Optional	Additional keys: not allowed
`headers.Idempotency-Key`	string	Optional	Minimum length: 1 Maximum length: 255
`body`	object	Optional	Additional keys: not allowed
`body.default_settings`	Model	Optional	Expand Create a schedule — request body — body default settings
`body.end_behavior`	string	Optional	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. One of: cancel, none, release, renew
`body.expand`	array	Optional	Specifies which fields in the response should be expanded.
`body.expand[]`	string	Each item	Maximum length: 5000
`body.metadata`	JSON	Optional	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`.
`body.metadata (anyOf 1)`	object	Alternative	Additional keys: see wildcard field
`body.metadata (anyOf 1).*`	string	Additional keys
`body.metadata (anyOf 2)`	string	Alternative	One of:
`body.pause_schedules`	JSON	Optional	Configures the subscription’s pause behavior and, optionally, its resume behavior. Only one entry is supported. Include a key to update an existing entry. Omit to leave an existing pause schedule unchanged, or pass "" to clear it.
`body.pause_schedules (anyOf 1)`	array	Alternative
`body.pause_schedules (anyOf 1)[]`	object	Each item
`body.pause_schedules (anyOf 1)[].key`	string	Optional	Maximum length: 40
`body.pause_schedules (anyOf 1)[].pause`	object	Optional
`body.pause_schedules (anyOf 1)[].pause.pause_at`	object	Optional
`body.pause_schedules (anyOf 1)[].pause.pause_at.timestamp`	integer	Optional	Format: unix-time
`body.pause_schedules (anyOf 1)[].pause.pause_at.type`	string	Required within parent	One of: now, timestamp
`body.pause_schedules (anyOf 1)[].pause.settings`	object	Optional
`body.pause_schedules (anyOf 1)[].pause.settings.bill_for`	object	Optional
`body.pause_schedules (anyOf 1)[].pause.settings.bill_for.outstanding_usage_through`	object	Optional
`body.pause_schedules (anyOf 1)[].pause.settings.bill_for.outstanding_usage_through.type`	string	Optional	One of: none, pause_at
`body.pause_schedules (anyOf 1)[].pause.settings.bill_for.unused_time_from`	object	Optional
`body.pause_schedules (anyOf 1)[].pause.settings.bill_for.unused_time_from.type`	string	Optional	One of: item_current_period_start, none, pause_at
`body.pause_schedules (anyOf 1)[].pause.settings.invoicing_behavior`	string	Optional	One of: invoice, pending_invoice_item
`body.pause_schedules (anyOf 1)[].pause.settings.type`	string	Optional	One of: subscription
`body.pause_schedules (anyOf 1)[].resume`	JSON	Optional
`body.pause_schedules (anyOf 1)[].resume (anyOf 1)`	object	Alternative
`body.pause_schedules (anyOf 1)[].resume (anyOf 1).resume_at`	object	Optional
`body.pause_schedules (anyOf 1)[].resume (anyOf 1).resume_at.duration`	object	Optional
`body.pause_schedules (anyOf 1)[].resume (anyOf 1).resume_at.duration.interval`	string	Required within parent	One of: day, month, week, year
`body.pause_schedules (anyOf 1)[].resume (anyOf 1).resume_at.duration.interval_count`	integer	Optional
`body.pause_schedules (anyOf 1)[].resume (anyOf 1).resume_at.timestamp`	integer	Optional	Format: unix-time
`body.pause_schedules (anyOf 1)[].resume (anyOf 1).resume_at.type`	string	Required within parent	One of: duration, now, timestamp
`body.pause_schedules (anyOf 1)[].resume (anyOf 1).settings`	object	Optional
`body.pause_schedules (anyOf 1)[].resume (anyOf 1).settings.billing_cycle_anchor`	string	Optional	One of: resume_at, unchanged
`body.pause_schedules (anyOf 1)[].resume (anyOf 1).settings.payment_behavior`	string	Optional	One of: resume_on_payment_attempt, resume_on_payment_success
`body.pause_schedules (anyOf 1)[].resume (anyOf 1).settings.proration_behavior`	string	Optional	One of: always_invoice, create_prorations, none
`body.pause_schedules (anyOf 1)[].resume (anyOf 2)`	string	Alternative	One of:
`body.pause_schedules (anyOf 2)`	string	Alternative	One of:
`body.phases`	array	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.
`body.phases[]`	object	Each item
`body.phases[].add_invoice_items`	array	Optional
`body.phases[].add_invoice_items[]`	Model	Each item	Expand Create a schedule — request body — body phases item add invoice items item
`body.phases[].application_fee_percent`	number	Optional
`body.phases[].automatic_tax`	object	Optional
`body.phases[].automatic_tax.enabled`	boolean	Required within parent
`body.phases[].automatic_tax.liability`	object	Optional
`body.phases[].automatic_tax.liability.account`	string	Optional
`body.phases[].automatic_tax.liability.type`	string	Required within parent	One of: account, self
`body.phases[].billing_cycle_anchor`	string	Optional	One of: automatic, phase_start
`body.phases[].billing_thresholds`	JSON	Optional
`body.phases[].billing_thresholds (anyOf 1)`	object	Alternative
`body.phases[].billing_thresholds (anyOf 1).amount_gte`	integer	Optional
`body.phases[].billing_thresholds (anyOf 1).reset_billing_cycle_anchor`	boolean	Optional
`body.phases[].billing_thresholds (anyOf 2)`	string	Alternative	One of:
`body.phases[].collection_method`	string	Optional	One of: charge_automatically, send_invoice
`body.phases[].default_payment_method`	string	Optional	Maximum length: 5000
`body.phases[].default_tax_rates`	JSON	Optional
`body.phases[].default_tax_rates (anyOf 1)`	array	Alternative
`body.phases[].default_tax_rates (anyOf 1)[]`	string	Each item	Maximum length: 5000
`body.phases[].default_tax_rates (anyOf 2)`	string	Alternative	One of:
`body.phases[].description`	JSON	Optional
`body.phases[].description (anyOf 1)`	string	Alternative	Maximum length: 500
`body.phases[].description (anyOf 2)`	string	Alternative	One of:
`body.phases[].discounts`	JSON	Optional
`body.phases[].discounts (anyOf 1)`	array	Alternative
`body.phases[].discounts (anyOf 1)[]`	object	Each item
`body.phases[].discounts (anyOf 1)[].coupon`	string	Optional	Maximum length: 5000
`body.phases[].discounts (anyOf 1)[].discount`	string	Optional	Maximum length: 5000
`body.phases[].discounts (anyOf 1)[].promotion_code`	string	Optional	Maximum length: 5000
`body.phases[].discounts (anyOf 2)`	string	Alternative	One of:
`body.phases[].duration`	object	Optional
`body.phases[].duration.interval`	string	Required within parent	One of: day, month, week, year
`body.phases[].duration.interval_count`	integer	Optional
`body.phases[].end_date`	JSON	Optional
`body.phases[].end_date (anyOf 1)`	integer	Alternative	Format: unix-time
`body.phases[].end_date (anyOf 2)`	string	Alternative	One of: now Maximum length: 5000
`body.phases[].invoice_settings`	Model	Optional	Expand Create a schedule — request body — body default settings invoice settings
`body.phases[].items`	array	Required within parent
`body.phases[].items[]`	Model	Each item	Expand Create a schedule — request body — body phases item items item
`body.phases[].metadata`	object	Optional	Additional keys: see wildcard field
`body.phases[].metadata.*`	string	Additional keys
`body.phases[].on_behalf_of`	string	Optional
`body.phases[].proration_behavior`	string	Optional	One of: always_invoice, create_prorations, none
`body.phases[].start_date`	JSON	Optional
`body.phases[].start_date (anyOf 1)`	integer	Alternative	Format: unix-time
`body.phases[].start_date (anyOf 2)`	string	Alternative	One of: now Maximum length: 5000
`body.phases[].transfer_data`	object	Optional
`body.phases[].transfer_data.amount_percent`	number	Optional
`body.phases[].transfer_data.destination`	string	Required within parent
`body.phases[].trial`	boolean	Optional
`body.phases[].trial_end`	JSON	Optional
`body.phases[].trial_end (anyOf 1)`	integer	Alternative	Format: unix-time
`body.phases[].trial_end (anyOf 2)`	string	Alternative	One of: now Maximum length: 5000
`body.proration_behavior`	string	Optional	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`. One of: always_invoice, create_prorations, none

Referenced models: Create a schedule — request body — body phases item add invoice items item, Create a schedule — request body — body default settings, Create a schedule — request body — body default settings invoice settings, Create a schedule — request body — body phases item items item

Response

Response media type: application/json. The table describes the pinned successful response. Referenced models link to their complete fields.

Field	Type	Presence	Description and constraints
`$`	Model	Root	Expand Cancel a schedule — response body

Referenced models: Cancel a schedule — response body

Schemas

712 more schemas are linked from the tables above, on the schema pages.

Cancel a schedule — response body

Field	Type	Presence	Description and constraints
`$`	object	Root	A subscription schedule allows you to create and manage the lifecycle of a subscription by predefining expected changes. Related guide: [Subscription schedules](https://docs.stripe.com/billing/subscriptions/subscription-schedules)
`application`	JSON	Optional
`application (anyOf 1)`	JSON	Alternative	ID of the Connect Application that created the schedule.
`application (anyOf 1) (anyOf 1)`	string	Alternative	Maximum length: 5000
`application (anyOf 1) (anyOf 2)`	Model	Alternative	Expand PostApplicationFeesIdRefund — response body — application / object: application
`application (anyOf 1) (anyOf 3)`	Model	Alternative	Expand Accept a quote — response body — application / value / deleted: True, object: application
`application (anyOf 2)`	null	Alternative
`billing_mode`	Model	Required within parent	Expand Cancel a schedule — response body — billing mode
`canceled_at`	JSON	Optional
`canceled_at (anyOf 1)`	JSON	Alternative
`canceled_at (anyOf 1) (anyOf 1)`	integer	Alternative	Time at which the subscription schedule was canceled. Measured in seconds since the Unix epoch. Format: unix-time
`canceled_at (anyOf 1) (anyOf 2)`	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
`canceled_at (anyOf 2)`	null	Alternative
`completed_at`	JSON	Optional
`completed_at (anyOf 1)`	JSON	Alternative
`completed_at (anyOf 1) (anyOf 1)`	integer	Alternative	Time at which the subscription schedule was completed. Measured in seconds since the Unix epoch. Format: unix-time
`completed_at (anyOf 1) (anyOf 2)`	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
`completed_at (anyOf 2)`	null	Alternative
`created`	JSON	Required within parent
`created (anyOf 1)`	integer	Alternative	Time at which the object was created. Measured in seconds since the Unix epoch. Format: unix-time
`created (anyOf 2)`	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
`current_phase`	JSON	Optional
`current_phase (anyOf 1)`	JSON	Alternative	Object representing the start and end dates for the current phase of the subscription schedule, if it is `active`.
`current_phase (anyOf 1) (anyOf 1)`	Model	Alternative	Expand Cancel a schedule — response body — current phase value end date, start date
`current_phase (anyOf 2)`	null	Alternative
`customer`	JSON	Required within parent	ID of the customer who owns the subscription schedule.
`customer (anyOf 1)`	string	Alternative	Maximum length: 5000
`customer (anyOf 2)`	Model	Alternative	Expand Create a customer — response body
`customer (anyOf 3)`	Model	Alternative	Expand Delete a customer — response body
`customer_account`	JSON	Optional
`customer_account (anyOf 1)`	string	Alternative	ID of the account who owns the subscription schedule. Maximum length: 5000
`customer_account (anyOf 2)`	null	Alternative
`default_settings`	Model	Required within parent	Expand Cancel a schedule — response body — default settings
`end_behavior`	string	Required within parent	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. Known values: cancel, none, release, renew
`id`	string	Required within parent	Unique identifier for the object. Maximum length: 5000
`livemode`	boolean	Required within parent	If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`.
`metadata`	JSON	Optional
`metadata (anyOf 1)`	object	Alternative	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. Additional keys: see wildcard field
`metadata (anyOf 1).*`	string	Additional keys	Maximum length: 500
`metadata (anyOf 2)`	null	Alternative
`object`	string	Required within parent	String representing the object's type. Objects of the same type share the same value. Known values: subscription_schedule
`pause_schedules`	array	Optional	The pause schedules for this subscription schedule.
`pause_schedules[]`	Model	Each item	Expand Cancel a schedule — response body — pause schedules item
`phases`	array	Required within parent	Configuration for the subscription schedule's phases.
`phases[]`	Model	Each item	Expand Cancel a schedule — response body — phases item
`released_at`	JSON	Optional
`released_at (anyOf 1)`	JSON	Alternative
`released_at (anyOf 1) (anyOf 1)`	integer	Alternative	Time at which the subscription schedule was released. Measured in seconds since the Unix epoch. Format: unix-time
`released_at (anyOf 1) (anyOf 2)`	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
`released_at (anyOf 2)`	null	Alternative
`released_subscription`	JSON	Optional
`released_subscription (anyOf 1)`	string	Alternative	ID of the subscription once managed by the subscription schedule (if it is released). Maximum length: 5000
`released_subscription (anyOf 2)`	null	Alternative
`status`	string	Required within parent	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). Known values: active, canceled, completed, not_started, released
`subscription`	JSON	Optional
`subscription (anyOf 1)`	JSON	Alternative	ID of the subscription managed by the subscription schedule.
`subscription (anyOf 1) (anyOf 1)`	string	Alternative	Maximum length: 5000
`subscription (anyOf 1) (anyOf 2)`	Model	Alternative	Expand Pause a subscription — response body
`subscription (anyOf 2)`	null	Alternative
`test_clock`	JSON	Optional
`test_clock (anyOf 1)`	JSON	Alternative	ID of the test clock this subscription schedule belongs to.
`test_clock (anyOf 1) (anyOf 1)`	string	Alternative	Maximum length: 5000
`test_clock (anyOf 1) (anyOf 2)`	Model	Alternative	Expand Create a test clock — response body
`test_clock (anyOf 2)`	null	Alternative

Referenced models: PostApplicationFeesIdRefund — response body — application / object: application, Create a customer — response body, Accept a quote — response body — application / value / deleted: True, object: application, Delete a customer — response body, Pause a subscription — response body, Cancel a schedule — response body — current phase value end date, start date, Cancel a schedule — response body — phases item, Cancel a schedule — response body — default settings, Cancel a schedule — response body — pause schedules item, Cancel a schedule — response body — billing mode, Create a test clock — response body

Create a schedule — request body — body default settings invoice settings

Field	Type	Presence	Description and constraints
`$`	object	Root
`account_tax_ids`	JSON	Optional
`account_tax_ids (anyOf 1)`	array	Alternative
`account_tax_ids (anyOf 1)[]`	string	Each item	Maximum length: 5000
`account_tax_ids (anyOf 2)`	string	Alternative	One of:
`custom_fields`	JSON	Optional
`custom_fields (anyOf 1)`	array	Alternative
`custom_fields (anyOf 1)[]`	object	Each item
`custom_fields (anyOf 1)[].name`	string	Required within parent	Maximum length: 40
`custom_fields (anyOf 1)[].value`	string	Required within parent	Maximum length: 140
`custom_fields (anyOf 2)`	string	Alternative	One of:
`days_until_due`	integer	Optional
`description`	JSON	Optional
`description (anyOf 1)`	string	Alternative	Maximum length: 1500
`description (anyOf 2)`	string	Alternative	One of:
`footer`	JSON	Optional
`footer (anyOf 1)`	string	Alternative	Maximum length: 5000
`footer (anyOf 2)`	string	Alternative	One of:
`issuer`	object	Optional
`issuer.account`	string	Optional
`issuer.type`	string	Required within parent	One of: account, self

Policy, approvals and errors

SDK function policy ID: stripe.postsubscriptionschedulesschedule. Catalog operation: PostSubscriptionSchedulesSchedule. Rules can name either ID; function rules distinguish managed calls and conservatively cover raw calls sharing the route. Existing grant permissions and policy rules apply. wait() returns an immediate result or waits for a required approval; it never approves the request itself. Persist the approval ID to resume after a restart.

Provider errors retain their response; JSON decoding raises ProviderAPIError for provider failures. ManagedOperationError identifies contract/input/retention errors. See error handling and provider-specific behavior. Sensitive input may be refused before approval storage. A decoding error never resubmits a write.

Pinned headers: {"Stripe-Version": "2026-09-30.endive"}

Official provider source

Report an issue with this page