Update a schedule

Billing

Subscription Schedule

Update a schedule

Updates an existing subscription schedule.

Parameters

metadatahash
Set of key-value pairs 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 of hashes

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.

phases.itemsarray of hashesRequired
List of configuration items, each with an attached price, to apply during this phase of the subscription schedule.
- phases.items.billing_thresholdshash
  Define thresholds at which an invoice will be sent, and the subscription advanced to a new billing period. Pass an empty string to remove previously-defined thresholds.
  phases.items.billing_thresholds.usage_gteintegerRequired
  Number of units that meets the billing threshold to advance the subscription to a new billing period (e.g., it takes 10 $5 units to meet a $50 monetary threshold)
- phases.items.discountsarray of hashes
  The coupons to redeem into discounts for the subscription item.
  phases.items.discounts.couponstring
  ID of the coupon to create a new discount for.
  phases.items.discounts.discountstring
  ID of an existing discount on the object (or one of its ancestors) to reuse.
  phases.items.discounts.promotion_codestring
  ID of the promotion code to create a new discount for.
- phases.items.metadatahash
  Set of key-value pairs that you can attach to a configuration item. Metadata on a configuration item will update the underlying subscription item’s metadata when the phase is entered, adding new keys and replacing existing keys. Individual keys in the subscription item’s metadata can be unset by posting an empty value to them in the configuration item’s metadata. To unset all keys in the subscription item’s metadata, update the subscription item directly or unset every key individually from the configuration item’s metadata.
- phases.items.pricestring
  The ID of the price object.
- phases.items.price_datahash
  Data used to generate a new Price object inline.
  phases.items.price_data.currencyenumRequired
  Three-letter ISO currency code, in lowercase. Must be a supported currency.
  phases.items.price_data.productstringRequired
  The ID of the Product that this Price will belong to.
  phases.items.price_data.recurringhashRequired
  The recurring components of a price such as interval and interval_count.
  phases.items.price_data.recurring.intervalenumRequired
  Specifies billing frequency. Either day, week, month or year.
  Possible enum values
  day
  month
  week
  year
  phases.items.price_data.recurring.interval_countinteger
  The number of intervals between subscription billings. For example, interval=month and interval_count=3 bills every 3 months. Maximum of three years interval allowed (3 years, 36 months, or 156 weeks).
  phases.items.price_data.tax_behaviorenumRecommended if calculating taxes
  Only required if a default tax behavior was not provided in the Stripe Tax settings. Specifies whether the price is considered inclusive of taxes or exclusive of taxes. One of inclusive, exclusive, or unspecified. Once specified as either inclusive or exclusive, it cannot be changed.
  Possible enum values
  exclusive
  inclusive
  unspecified
  phases.items.price_data.unit_amountinteger
  A positive integer in cents (or 0 for a free price) representing how much to charge.
  phases.items.price_data.unit_amount_decimalstringRequired conditionally
  Same as unit_amount, but accepts a decimal value in cents with at most 12 decimal places. Only one of unit_amount and unit_amount_decimal can be set.
- phases.items.quantityinteger
  Quantity for the given price. Can be set only if the price’s usage_type is licensed and not metered.
- phases.items.tax_ratesarray of strings
  A list of Tax Rate ids. These Tax Rates will override the default_tax_rates on the Subscription. When updating, pass an empty string to remove previously-defined tax rates.

phases.add_invoice_itemsarray of hashes

A list of prices and quantities that will generate invoice items appended to the next invoice for this phase. You may pass up to 20 items.

phases.add_invoice_items.discountsarray of hashes
The coupons to redeem into discounts for the item.
- phases.add_invoice_items.discounts.couponstring
  ID of the coupon to create a new discount for.
- phases.add_invoice_items.discounts.discountstring
  ID of an existing discount on the object (or one of its ancestors) to reuse.
- phases.add_invoice_items.discounts.promotion_codestring
  ID of the promotion code to create a new discount for.

phases.add_invoice_items.metadatahash
Set of key-value pairs 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.

phases.add_invoice_items.periodhash

The period associated with this invoice item. If not set, period.start.type defaults to max_item_period_start and period.end.type defaults to min_item_period_end.

phases.add_invoice_items.period.endhashRequired

End of the invoice item period.

phases.add_invoice_items.period.end.typeenumRequired

Select how to calculate the end of the invoice item period.

Possible enum values

min_item_period_end

The minimum current_period_end of all underlying subscription items whose periods overlap this phase

phase_end

End of the phase

timestamp

Custom timestamp to use for the end of the invoice item period

phases.add_invoice_items.period.end.timestamptimestamp
A precise Unix timestamp for the end of the invoice item period. Must be greater than or equal to period.start.

phases.add_invoice_items.period.starthashRequired

Start of the invoice item period.

phases.add_invoice_items.period.start.typeenumRequired

Select how to calculate the start of the invoice item period.

Possible enum values

max_item_period_start

The maximum current_period_start of all underlying subscription items whose periods overlap this phase

phase_start

Start of the phase

timestamp

Custom timestamp to use for the start of the invoice item period

phases.add_invoice_items.period.start.timestamptimestamp
A precise Unix timestamp for the start of the invoice item period. Must be less than or equal to period.end.

phases.add_invoice_items.pricestring
The ID of the price object. One of price or price_data is required.

phases.add_invoice_items.price_datahash
Data used to generate a new Price object inline. One of price or price_data is required.
- phases.add_invoice_items.price_data.currencyenumRequired
  Three-letter ISO currency code, in lowercase. Must be a supported currency.
- phases.add_invoice_items.price_data.productstringRequired
  The ID of the Product that this Price will belong to.
- phases.add_invoice_items.price_data.tax_behaviorenumRecommended if calculating taxes
  Only required if a default tax behavior was not provided in the Stripe Tax settings. Specifies whether the price is considered inclusive of taxes or exclusive of taxes. One of inclusive, exclusive, or unspecified. Once specified as either inclusive or exclusive, it cannot be changed.
  Possible enum values
  exclusive
  inclusive
  unspecified
- phases.add_invoice_items.price_data.unit_amountinteger
  A positive integer in cents (or 0 for a free price) representing how much to charge or a negative integer representing the amount to credit to the customer.
- phases.add_invoice_items.price_data.unit_amount_decimalstringRequired conditionally
  Same as unit_amount, but accepts a decimal value in cents with at most 12 decimal places. Only one of unit_amount and unit_amount_decimal can be set.

phases.add_invoice_items.quantityinteger
Quantity for this item. Defaults to 1.

phases.add_invoice_items.tax_ratesarray of strings
The tax rates which apply to the item. When set, the default_tax_rates do not apply to this item.

phases.application_fee_percentfloatConnect only
A non-negative decimal between 0 and 100, with at most two decimal places. This represents the percentage of the subscription invoice total that will be transferred to the application owner’s Stripe account. The request must be made by a platform account on a connected account in order to set an application fee percentage. For more information, see the application fees documentation.

phases.automatic_taxhash

Automatic tax settings for this phase.

phases.automatic_tax.enabledbooleanRequired
Enabled automatic tax calculation which will automatically compute tax rates on all invoices generated by the subscription.

phases.automatic_tax.liabilityhashConnect only

The account that’s liable for tax. If set, the business address and tax registrations required to perform the tax calculation are loaded from this account. The tax transaction is returned in the report of the connected account.

phases.automatic_tax.liability.typeenumRequired

Type of the account referenced in the request.

Possible enum values

account

Indicates that the account being referenced is a connected account which is different from the account making the API request but related to it.

self

Indicates that the account being referenced is the account making the API request.

phases.automatic_tax.liability.accountstringRequired only if type is account
The connected account being referenced when type is account.

phases.billing_cycle_anchorenum
Can be set to phase_start to set the anchor to the start of the phase or automatic to automatically change it if needed. Cannot be set to phase_start if this phase specifies a trial. For more information, see the billing cycle documentation.
Possible enum values
automatic
phase_start

phases.billing_thresholdshash
Define thresholds at which an invoice will be sent, and the subscription advanced to a new billing period. Pass an empty string to remove previously-defined thresholds.
- phases.billing_thresholds.amount_gteinteger
  Monetary threshold that triggers the subscription to advance to a new billing period
- phases.billing_thresholds.reset_billing_cycle_anchorboolean
  Indicates if the billing_cycle_anchor should be reset when a threshold is reached. If true, billing_cycle_anchor will be updated to the date/time the threshold was last reached; otherwise, the value will remain unchanged.

phases.collection_methodenum
Either charge_automatically, or send_invoice. When charging automatically, Stripe will attempt to pay the underlying subscription at the end of each billing cycle using the default source attached to the customer. When sending an invoice, Stripe will email your customer an invoice with payment instructions and mark the subscription as active. Defaults to charge_automatically on creation.
Possible enum values
charge_automatically
send_invoice

phases.default_payment_methodstring
ID of the default payment method for the subscription schedule. It must belong to the customer associated with the subscription schedule. If not set, invoices will use the default payment method in the customer’s invoice settings.

phases.default_tax_ratesarray of strings
A list of Tax Rate ids. These Tax Rates will set the Subscription’s default_tax_rates, which means they will be the Invoice’s default_tax_rates for any Invoices issued by the Subscription during this Phase.

phases.descriptionstring
Subscription description, meant to be displayable to the customer. Use this field to optionally store an explanation of the subscription for rendering in Stripe surfaces and certain local payment methods UIs.

phases.discountsarray of hashes
The coupons to redeem into discounts for the schedule phase. If not specified, inherits the discount from the subscription’s customer. Pass an empty string to avoid inheriting any discounts.
- phases.discounts.couponstring
  ID of the coupon to create a new discount for.
- phases.discounts.discountstring
  ID of an existing discount on the object (or one of its ancestors) to reuse.
- phases.discounts.promotion_codestring
  ID of the promotion code to create a new discount for.

phases.durationhash
The number of intervals the phase should last. If set, end_date must not be set.
- phases.duration.intervalenumRequired
  Specifies phase duration. Either day, week, month or year.
  Possible enum values
  day
  month
  week
  year
- phases.duration.interval_countinteger
  The multiplier applied to the interval.

phases.end_datetimestamp | string
The date at which this phase of the subscription schedule ends. If set, iterations must not be set.

phases.invoice_settingshash

All invoices will be billed using the specified settings.

phases.invoice_settings.account_tax_idsarray of strings
The account tax IDs associated with this phase of the subscription schedule. Will be set on invoices generated by this phase of the subscription schedule.

phases.invoice_settings.days_until_dueinteger
Number of days within which a customer must pay invoices generated by this subscription schedule. This value will be null for subscription schedules where billing=charge_automatically.

phases.invoice_settings.issuerhashConnect only

The connected account that issues the invoice. The invoice is presented with the branding and support information of the specified account.

phases.invoice_settings.issuer.typeenumRequired

Type of the account referenced in the request.

Possible enum values

account

Indicates that the account being referenced is a connected account which is different from the account making the API request but related to it.

self

Indicates that the account being referenced is the account making the API request.

phases.invoice_settings.issuer.accountstringRequired only if type is account
The connected account being referenced when type is account.

phases.iterationsintegerDeprecated
Integer representing the multiplier applied to the price interval. For example, iterations=2 applied to a price with interval=month and interval_count=3 results in a phase of duration 2 * 3 months = 6 months. If set, end_date must not be set. This parameter is deprecated and will be removed in a future version. Use duration instead.

phases.metadatahash
Set of key-value pairs that you can attach to a phase. Metadata on a schedule’s phase will update the underlying subscription’s metadata when the phase is entered, adding new keys and replacing existing keys in the subscription’s metadata. Individual keys in the subscription’s metadata can be unset by posting an empty value to them in the phase’s metadata. To unset all keys in the subscription’s metadata, update the subscription directly or unset every key individually from the phase’s metadata.

phases.on_behalf_ofstringConnect only
The account on behalf of which to charge, for each of the associated subscription’s invoices.

phases.proration_behaviorenum

Controls whether the subscription schedule should create prorations when transitioning to this phase if there is a difference in billing configuration. It’s different from the request-level proration_behavior parameter which controls what happens if the update request affects the billing configuration (item price, quantity, etc.) of the current phase.

Possible enum values

always_invoice

Prorate changes, and force an invoice to be immediately created for any prorations.

create_prorations

Prorate changes, but leave any prorations as pending invoice items to be picked up on the customer’s next invoice.

none

Does not create any prorations.

phases.start_datetimestamp | string
The date at which this phase of the subscription schedule starts or now. Must be set on the first phase.

phases.transfer_datahashConnect only
The data with which to automatically create a Transfer for each of the associated subscription’s invoices.
- phases.transfer_data.destinationstringRequired
  ID of an existing, connected Stripe account.
- phases.transfer_data.amount_percentfloat
  A non-negative decimal between 0 and 100, with at most two decimal places. This represents the percentage of the subscription invoice total that will be transferred to the destination account. By default, the entire amount is transferred to the destination.

phases.trialboolean
If set to true the entire phase is counted as a trial and the customer will not be charged for any fees.

phases.trial_endtimestamp | string
Sets the phase to trialing from the start date to this date. Must be before the phase end date, can not be combined with trial

proration_behaviorenum

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.

Possible enum values

always_invoice

Prorate changes, and force an invoice to be immediately created for any prorations.

create_prorations

Prorate changes, but leave any prorations as pending invoice items to be picked up on the customer’s next invoice.

none

Does not create any prorations.

More parameters

default_settingshash

Object representing the subscription schedule’s default settings.

default_settings.application_fee_percentfloatConnect only
A non-negative decimal between 0 and 100, with at most two decimal places. This represents the percentage of the subscription invoice total that will be transferred to the application owner’s Stripe account. The request must be made by a platform account on a connected account in order to set an application fee percentage. For more information, see the application fees documentation.

default_settings.automatic_taxhash

Default settings for automatic tax computation.

default_settings.automatic_tax.enabledbooleanRequired
Enabled automatic tax calculation which will automatically compute tax rates on all invoices generated by the subscription.

default_settings.automatic_tax.liabilityhashConnect only

default_settings.automatic_tax.liability.typeenumRequired

Type of the account referenced in the request.

Possible enum values

account

Indicates that the account being referenced is a connected account which is different from the account making the API request but related to it.

self

Indicates that the account being referenced is the account making the API request.

default_settings.automatic_tax.liability.accountstringRequired only if type is account
The connected account being referenced when type is account.

default_settings.billing_cycle_anchorenum
Can be set to phase_start to set the anchor to the start of the phase or automatic to automatically change it if needed. Cannot be set to phase_start if this phase specifies a trial. For more information, see the billing cycle documentation.
Possible enum values
automatic
phase_start

default_settings.billing_thresholdshash
Define thresholds at which an invoice will be sent, and the subscription advanced to a new billing period. Pass an empty string to remove previously-defined thresholds.
- default_settings.billing_thresholds.amount_gteinteger
  Monetary threshold that triggers the subscription to advance to a new billing period
- default_settings.billing_thresholds.reset_billing_cycle_anchorboolean
  Indicates if the billing_cycle_anchor should be reset when a threshold is reached. If true, billing_cycle_anchor will be updated to the date/time the threshold was last reached; otherwise, the value will remain unchanged.

default_settings.collection_methodenum
Either charge_automatically, or send_invoice. When charging automatically, Stripe will attempt to pay the underlying subscription at the end of each billing cycle using the default source attached to the customer. When sending an invoice, Stripe will email your customer an invoice with payment instructions and mark the subscription as active. Defaults to charge_automatically on creation.
Possible enum values
charge_automatically
send_invoice

default_settings.default_payment_methodstring
ID of the default payment method for the subscription schedule. It must belong to the customer associated with the subscription schedule. If not set, invoices will use the default payment method in the customer’s invoice settings.

default_settings.descriptionstring
Subscription description, meant to be displayable to the customer. Use this field to optionally store an explanation of the subscription for rendering in Stripe surfaces and certain local payment methods UIs.

default_settings.invoice_settingshash

All invoices will be billed using the specified settings.

default_settings.invoice_settings.account_tax_idsarray of strings
The account tax IDs associated with the subscription schedule. Will be set on invoices generated by the subscription schedule.

default_settings.invoice_settings.days_until_dueinteger
Number of days within which a customer must pay invoices generated by this subscription schedule. This value will be null for subscription schedules where collection_method=charge_automatically.

default_settings.invoice_settings.issuerhashConnect only

The connected account that issues the invoice. The invoice is presented with the branding and support information of the specified account.

default_settings.invoice_settings.issuer.typeenumRequired

Type of the account referenced in the request.

Possible enum values

account

Indicates that the account being referenced is a connected account which is different from the account making the API request but related to it.

self

Indicates that the account being referenced is the account making the API request.

default_settings.invoice_settings.issuer.accountstringRequired only if type is account
The connected account being referenced when type is account.

default_settings.on_behalf_ofstringConnect only
The account on behalf of which to charge, for each of the associated subscription’s invoices.

default_settings.transfer_datahashConnect only
The data with which to automatically create a Transfer for each of the associated subscription’s invoices.
- default_settings.transfer_data.destinationstringRequired
  ID of an existing, connected Stripe account.
- default_settings.transfer_data.amount_percentfloat
  A non-negative decimal between 0 and 100, with at most two decimal places. This represents the percentage of the subscription invoice total that will be transferred to the destination account. By default, the entire amount is transferred to the destination.

end_behaviorenum
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.
Possible enum values
cancel
Cancel the underlying subscription when the subscription schedule ends.
release
Persist the underlying subscription in its current state when the subscription schedule ends.

Returns

Returns an updated subscription schedule object if the call succeeded.

POST /v1/subscription_schedules/:id

Server-side language

Stripe.api_key = 'sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2'
subscription_schedule = Stripe::SubscriptionSchedule.update(
  'sub_sched_1Mr3YdLkdIwHu7ixjop3qtff',
  {end_behavior: 'release'},
)

Response

{
  "id": "sub_sched_1Mr3YdLkdIwHu7ixjop3qtff",
  "object": "subscription_schedule",
  "application": null,
  "canceled_at": null,
  "completed_at": null,
  "created": 1680113835,
  "current_phase": null,
  "customer": "cus_NcI8FsMbh0OeFs",
  "default_settings": {
    "application_fee_percent": null,
    "automatic_tax": {
      "enabled": false,
      "liability": null
    },
    "billing_cycle_anchor": "automatic",
    "collection_method": "charge_automatically",
    "default_payment_method": null,
    "default_source": null,
    "description": null,
    "invoice_settings": {
      "issuer": {
        "type": "self"
      }
    },
    "on_behalf_of": null,
    "transfer_data": null
  },
  "end_behavior": "release",
  "livemode": false,
  "metadata": {},
  "phases": [
    {
      "add_invoice_items": [],
      "application_fee_percent": null,
      "billing_cycle_anchor": null,
      "collection_method": null,
      "currency": "usd",
      "default_payment_method": null,
      "default_tax_rates": [],
      "description": null,
      "end_date": 1712339228,
      "invoice_settings": null,
      "items": [
        {
          "metadata": {},
          "plan": "price_1Mr3YcLkdIwHu7ixYCFhXHNb",
          "price": "price_1Mr3YcLkdIwHu7ixYCFhXHNb",
          "quantity": 1,
          "tax_rates": []
        }
      ],
      "metadata": {},
      "on_behalf_of": null,
      "proration_behavior": "create_prorations",
      "start_date": 1680716828,
      "transfer_data": null,
      "trial_end": null
    }
  ],
  "released_at": null,
  "released_subscription": null,
  "renewal_interval": null,
  "status": "not_started",
  "subscription": null,
  "test_clock": null
}

Update a schedule

Parameters

metadatahash

phasesarray of hashes

phases.itemsarray of hashesRequired

phases.items.billing_thresholdshash

phases.items.billing_thresholds.usage_gteintegerRequired

phases.items.discountsarray of hashes

phases.items.discounts.couponstring

phases.items.discounts.discountstring

phases.items.discounts.promotion_codestring

phases.items.metadatahash

phases.items.pricestring

phases.items.price_datahash

phases.items.price_data.currencyenumRequired

phases.items.price_data.productstringRequired

phases.items.price_data.recurringhashRequired

phases.items.price_data.recurring.intervalenumRequired

phases.items.price_data.recurring.interval_countinteger

phases.items.price_data.tax_behaviorenumRecommended if calculating taxes

phases.items.price_data.unit_amountinteger

phases.items.price_data.unit_amount_decimalstringRequired conditionally

phases.items.quantityinteger

phases.items.tax_ratesarray of strings

phases.add_invoice_itemsarray of hashes

phases.add_invoice_items.discountsarray of hashes

phases.add_invoice_items.discounts.couponstring

phases.add_invoice_items.discounts.discountstring

phases.add_invoice_items.discounts.promotion_codestring

phases.add_invoice_items.metadatahash

phases.add_invoice_items.periodhash

phases.add_invoice_items.period.endhashRequired

phases.add_invoice_items.period.end.typeenumRequired

phases.add_invoice_items.period.end.timestamptimestamp

phases.add_invoice_items.period.starthashRequired

phases.add_invoice_items.period.start.typeenumRequired

phases.add_invoice_items.period.start.timestamptimestamp

phases.add_invoice_items.pricestring

phases.add_invoice_items.price_datahash

phases.add_invoice_items.price_data.currencyenumRequired

phases.add_invoice_items.price_data.productstringRequired

phases.add_invoice_items.price_data.tax_behaviorenumRecommended if calculating taxes

phases.add_invoice_items.price_data.unit_amountinteger

phases.add_invoice_items.price_data.unit_amount_decimalstringRequired conditionally

phases.add_invoice_items.quantityinteger

phases.add_invoice_items.tax_ratesarray of strings

phases.application_fee_percentfloatConnect only

phases.automatic_taxhash

phases.automatic_tax.enabledbooleanRequired

phases.automatic_tax.liabilityhashConnect only

phases.automatic_tax.liability.typeenumRequired

phases.automatic_tax.liability.accountstringRequired only if type is account

phases.billing_cycle_anchorenum

phases.billing_thresholdshash

phases.billing_thresholds.amount_gteinteger

phases.billing_thresholds.reset_billing_cycle_anchorboolean

phases.collection_methodenum

phases.default_payment_methodstring

phases.default_tax_ratesarray of strings

phases.descriptionstring

phases.discountsarray of hashes

phases.discounts.couponstring

phases.discounts.discountstring

phases.discounts.promotion_codestring

phases.durationhash

phases.duration.intervalenumRequired

phases.duration.interval_countinteger

phases.end_datetimestamp | string

phases.invoice_settingshash

phases.invoice_settings.account_tax_idsarray of strings

phases.invoice_settings.days_until_dueinteger

phases.invoice_settings.issuerhashConnect only

phases.invoice_settings.issuer.typeenumRequired

phases.invoice_settings.issuer.accountstringRequired only if type is account

phases.iterationsintegerDeprecated

phases.metadatahash

phases.on_behalf_ofstringConnect only

phases.proration_behaviorenum

phases.start_datetimestamp | string

phases.transfer_datahashConnect only

More parameters