Create a schedule

Billing

Subscription Schedule

Create a schedule

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

Parameters

customerstring
The identifier of the customer to create the subscription schedule for.

metadataobject
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 objects

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.

phases.itemsarray of objectsRequired
List of configuration items, each with an attached price, to apply during this phase of the subscription schedule.
- phases.items.billing_thresholdsobject
  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 objects
  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.metadataobject
  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_dataobject
  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.recurringobjectRequired
  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 objects
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 objects
  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.pricestring
  The ID of the price object. One of price or price_data is required.
- phases.add_invoice_items.price_dataobject
  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_taxobject

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.liabilityobjectConnect 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_thresholdsobject
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.currencyenum
Three-letter ISO currency code, in lowercase. Must be a supported currency.

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 objects
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.end_datetimestamp
The date at which this phase of the subscription schedule ends. If set, iterations must not be set.

phases.invoice_settingsobject

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.issuerobjectConnect 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.iterationsinteger
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.

phases.metadataobject
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.transfer_dataobjectConnect 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
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

start_datetimestamp | string
When the subscription schedule starts. We recommend using now so that it starts the subscription immediately. 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.

More parameters

billing_modeobject
Controls how prorations and invoices for subscriptions are calculated and orchestrated.
- billing_mode.typeenumRequired
  Controls the calculation and orchestration of prorations and invoices for subscriptions.
  Possible enum values
  classic
  Calculations for subscriptions and invoices are based on legacy defaults.
  flexible
  Supports more flexible calculation and orchestration options for subscriptions and invoices.

default_settingsobject

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_taxobject

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.liabilityobjectConnect 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_thresholdsobject
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_settingsobject

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.issuerobjectConnect 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_dataobjectConnect 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.

from_subscriptionstring
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.

Returns

Returns a subscription schedule object if the call succeeded.

POST /v1/subscription_schedules

curl https://api.stripe.com/v1/subscription_schedules \
  -u "sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2:" \
  -H "Stripe-Version: 2025-06-30.basil" \
  -d customer=cus_NcI8FsMbh0OeFs \
  -d start_date=1787130418 \
  -d end_behavior=release \
  -d "phases[0][items][0][price]"=price_1Mr3YcLkdIwHu7ixYCFhXHNb \
  -d "phases[0][items][0][quantity]"=1 \
  -d "phases[0][iterations]"=12

Response

{
  "id": "sub_sched_1Mr3YdLkdIwHu7ixjop3qtff",
  "object": "subscription_schedule",
  "application": null,
  "canceled_at": null,
  "completed_at": null,
  "created": 1724058651,
  "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,
      "discounts": null,
      "end_date": 1818666418,
      "invoice_settings": null,
      "items": [
        {
          "discounts": null,
          "metadata": {},
          "plan": "price_1Mr3YcLkdIwHu7ixYCFhXHNb",
          "price": "price_1Mr3YcLkdIwHu7ixYCFhXHNb",
          "quantity": 1,
          "tax_rates": []
        }
      ],
      "metadata": {},
      "on_behalf_of": null,
      "proration_behavior": "create_prorations",
      "start_date": 1787130418,
      "transfer_data": null,
      "trial_end": null
    }
  ],
  "released_at": null,
  "released_subscription": null,
  "renewal_interval": null,
  "status": "not_started",
  "subscription": null,
  "test_clock": null
}

Create a schedule

Parameters

customerstring

metadataobject

phasesarray of objects

phases.itemsarray of objectsRequired

phases.items.billing_thresholdsobject

phases.items.billing_thresholds.usage_gteintegerRequired

phases.items.discountsarray of objects

phases.items.discounts.couponstring

phases.items.discounts.discountstring

phases.items.discounts.promotion_codestring

phases.items.metadataobject

phases.items.pricestring

phases.items.price_dataobject

phases.items.price_data.currencyenumRequired

phases.items.price_data.productstringRequired

phases.items.price_data.recurringobjectRequired

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 objects

phases.add_invoice_items.discountsarray of objects

phases.add_invoice_items.discounts.couponstring

phases.add_invoice_items.discounts.discountstring

phases.add_invoice_items.discounts.promotion_codestring

phases.add_invoice_items.pricestring

phases.add_invoice_items.price_dataobject

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_taxobject

phases.automatic_tax.enabledbooleanRequired

phases.automatic_tax.liabilityobjectConnect only

phases.automatic_tax.liability.typeenumRequired

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

phases.billing_cycle_anchorenum

phases.billing_thresholdsobject

phases.billing_thresholds.amount_gteinteger

phases.billing_thresholds.reset_billing_cycle_anchorboolean

phases.collection_methodenum

phases.currencyenum

phases.default_payment_methodstring

phases.default_tax_ratesarray of strings

phases.descriptionstring

phases.discountsarray of objects

phases.discounts.couponstring

phases.discounts.discountstring

phases.discounts.promotion_codestring

phases.end_datetimestamp

phases.invoice_settingsobject

phases.invoice_settings.account_tax_idsarray of strings

phases.invoice_settings.days_until_dueinteger

phases.invoice_settings.issuerobjectConnect only

phases.invoice_settings.issuer.typeenumRequired

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

phases.iterationsinteger

phases.metadataobject

phases.on_behalf_ofstringConnect only

phases.proration_behaviorenum

phases.transfer_dataobjectConnect only

phases.transfer_data.destinationstringRequired

phases.transfer_data.amount_percentfloat

phases.trialboolean

phases.trial_endtimestamp

start_datetimestamp | string

More parametersCollapse all

billing_modeobject

billing_mode.typeenumRequired

default_settingsobject

default_settings.application_fee_percentfloatConnect only

More parameters