Creates a new subscription on an existing customer. Each customer can have up to 500 active or scheduled subscriptions.

When you create a subscription with collection_method=charge_automatically, the first invoice is finalized as part of the request. The payment_behavior parameter determines the exact behavior of the initial payment.

To start subscriptions where the first invoice always begins in a draft status, use subscription schedules instead. Schedules provide the flexibility to model more complex billing configurations that change over time.

Parameters

• automatic_taxobject

  Automatic tax settings for this subscription.

  Show child parameters

• currencyenum

  Three-letter ISO currency code, in lowercase. Must be a supported currency.

• customerstring

  The identifier of the customer to subscribe.

• customer_accountstring

  The identifier of the account representing the customer to subscribe.

• default_payment_methodstring

  ID of the default payment method for the subscription. It must belong to the customer associated with the subscription. This takes precedence over default_source. If neither are set, invoices will use the customer’s invoice_settings.default_payment_method or default_source.

• descriptionstring

  The subscription’s 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.

  The maximum length is 500 characters.

• itemsarray of objectsRequired

  A list of up to 20 subscription items, each with an attached price.

  Show child parameters

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

• payment_behaviorenum

  Controls how Stripe handles the first invoice when payment is required and collection_method=charge_automatically. Subscriptions with collection_method=send_invoice are automatically activated regardless of the first Invoice status.

  Possible enum values

  allow_incomplete This is the default behavior since 2019-03-14. If payment fails, the Subscription is created with status=incomplete, otherwise status=active. This behavior allows you to manage scenarios where additional customer actions are needed to pay the Invoice. For example, SCA regulations might require 3DS authentication to complete payment. See the SCA Migration Guide for Billing to learn more.

  default_incomplete When the first invoice requires payment, creates a Subscription with status=incomplete without attempting payment, otherwise status=active. You must request explicit confirmation of the Invoice’s PaymentIntent to activate the subscription. The resulting Invoice has auto_advance=false, so Stripe doesn’t automatically attempt payment, retry payment, or finalize the subscription.

  error_if_incomplete If payment fails, return an HTTP 402 status code and don’t create the subscription. This behavior doesn’t support payments that require user action, such as 3DS authentication, because it returns an error instead of creating a PaymentIntent with status=requires_action. This behavior was the default for API versions before 2019-03-14.

  pending_if_incomplete This behavior is exclusive to Subscription updates and cannot be used for creation.

More parameters

Expand all

• add_invoice_itemsarray of objects

• application_fee_percentfloatConnect only

• backdate_start_datetimestamp

• billing_cycle_anchortimestamp

• billing_cycle_anchor_configobject

• billing_modeobject

• billing_schedulesarray of objects

• billing_thresholdsobject

• cancel_attimestamp | enum

• cancel_at_period_endboolean

• collection_methodenum

• days_until_dueinteger

• default_sourcestring

• default_tax_ratesarray of strings

• discountsarray of objects

• invoice_settingsobject

• off_sessionboolean

• on_behalf_ofstring

• payment_settingsobject

• pending_invoice_item_intervalobject

• proration_behaviorenum

• transfer_dataobjectConnect only

• trial_endstring | timestamp

• trial_from_planboolean

• trial_period_daysinteger

• trial_settingsobject

Updates an existing subscription to match the specified parameters. When changing prices or quantities, we optionally prorate the price we charge next month to make up for any price changes. To preview how the proration is calculated, use the create preview endpoint.

By default, we prorate subscription changes. For example, if a customer signs up on May 1 for a 100 USD price, they’ll be billed 100 USD immediately. If on May 15 they switch to a 200 USD price, then on June 1 they’ll be billed 250 USD (200 USD for a renewal of her subscription, plus a 50 USD prorating adjustment for half of the previous month’s 100 USD difference). Similarly, a downgrade generates a credit that is applied to the next invoice. We also prorate when you make quantity changes.

Switching prices does not normally change the billing date or generate an immediate charge unless:

• The billing interval is changed (for example, from monthly to yearly).
• The subscription moves from free to paid.
• A trial starts or ends.

In these cases, we apply a credit for the unused time on the previous price, immediately charge the customer using the new price, and reset the billing date. Learn about how Stripe immediately attempts payment for subscription changes.

If you want to charge for an upgrade immediately, pass proration_behavior as always_invoice to create prorations, automatically invoice the customer for those proration adjustments, and attempt to collect payment. If you pass create_prorations, the prorations are created but not automatically invoiced. If you want to bill the customer for the prorations before the subscription’s renewal date, you need to manually invoice the customer.

If you don’t want to prorate, set the proration_behavior option to none. With this option, the customer is billed 100 USD on May 1 and 200 USD on June 1. Similarly, if you set proration_behavior to none when switching between different billing intervals (for example, from monthly to yearly), we don’t generate any credits for the old subscription’s unused time. We still reset the billing date and bill immediately for the new subscription.

Updating the quantity on a subscription many times in an hour may result in rate limiting. If you need to bill for a frequently changing quantity, consider integrating usage-based billing instead.

Parameters

• automatic_taxobject

  Automatic tax settings for this subscription. We recommend you only include this parameter when the existing value is being changed.

  Show child parameters

• default_payment_methodstring

  ID of the default payment method for the subscription. It must belong to the customer associated with the subscription. This takes precedence over default_source. If neither are set, invoices will use the customer’s invoice_settings.default_payment_method or default_source.

• descriptionstring

  The subscription’s 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.

  The maximum length is 500 characters.

• itemsarray of objects

  A list of up to 20 subscription items, each with an attached price.

  Show child parameters

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

• payment_behaviorenum

  Controls how Stripe handles payment when a subscription update requires payment and collection_method=charge_automatically.

  Possible enum values

  allow_incomplete This is the default behavior since 2019-03-14. Transition the subscription to status=past_due if payment fails. If you have payment retries configured, Stripe automatically retries the payment. If the payment requires action, you receive an invoice.payment_action_required webhook and must manage additional user actions. For example, SCA regulations might require 3DS authentication to complete payment. See the SCA Migration Guide for Billing to learn more.

  default_incomplete When payment is required, transition the subscription to status=past_due without attempting payment. You must request explicit confirmation of the Invoice’s PaymentIntent. The resulting Invoice has auto_advance=false, so Stripe doesn’t automatically attempt payment, retry payment, or finalize the subscription.

  error_if_incomplete If payment fails, return an HTTP 402 status code and don’t update the subscription. This behavior doesn’t support payments that require user action, such as 3DS authentication, because it returns an error instead of creating a PaymentIntent with status=requires_action. This behavior was the default for API versions before 2019-03-14.

  pending_if_incomplete If payment fails, Stripe creates a pending update, which applies only if the payment eventually succeeds. This behavior doesn’t support all attributes and payment methods. This option is the simplest way to ensure the customer completes payment before Stripe applies the update.

• proration_behaviorenum

  Determines how to handle prorations when the billing cycle changes (e.g., when switching plans, resetting billing_cycle_anchor=now, or starting a trial), or if an item’s quantity changes. The default value is create_prorations.

  Possible enum values

  always_invoice Always invoice immediately for prorations.

  create_prorations Will cause proration invoice items to be created when applicable. These proration items will only be invoiced immediately under certain conditions.

  none Disable creating prorations in this request.

More parameters

Expand all

• add_invoice_itemsarray of objects

• application_fee_percentfloatConnect only

• billing_cycle_anchorstring

• billing_schedulesarray of objects

• billing_thresholdsobject

• cancel_attimestamp | enum

• cancel_at_period_endboolean

• cancellation_detailsobject

• collection_methodenum

• days_until_dueinteger

• default_sourcestring

• default_tax_ratesarray of strings

• discountsarray of objects

• invoice_settingsobject

• off_sessionboolean

• on_behalf_ofstring

• pause_collectionobject

• payment_settingsobject

• pending_invoice_item_intervalobject

• proration_datetimestamp

• transfer_dataobjectConnect only

• trial_endstring | timestamp

• trial_from_planboolean

• trial_settingsobject

Retrieves the subscription with the given ID.

Parameters

No parameters.