Attributes

• idstring

  Unique identifier for the object.

• automatic_taxobject

  Automatic tax settings for this subscription.

  Show child attributes

• currencyenum

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

• customerstringExpandable

  ID of the customer who owns the subscription.

• customer_accountnullable string

  ID of the account representing the customer who owns the subscription.

• default_payment_methodnullable stringExpandable

  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.

• descriptionnullable string

  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.

• itemsobject

  List of subscription items, each with an attached price.

  Show child attributes

• latest_invoicenullable stringExpandable

  The most recent invoice this subscription has generated over its lifecycle (for example, when it cycles or is updated).

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

• pending_setup_intentnullable stringExpandable

  You can use this SetupIntent to collect user authentication when creating a subscription without immediate payment or updating a subscription’s payment method, allowing you to optimize for off-session payments. Learn more in the SCA Migration Guide.

• pending_updatenullable object

  If specified, pending updates that will be applied to the subscription once the latest_invoice has been paid.

  Show child attributes

• statusenum

  Possible values are incomplete, incomplete_expired, trialing, active, past_due, canceled, unpaid, or paused.

  For collection_method=charge_automatically a subscription moves into incomplete if the initial payment attempt fails. A subscription in this status can only have metadata and default_source updated. Once the first invoice is paid, the subscription moves into an active status. If the first invoice is not paid within 23 hours, the subscription transitions to incomplete_expired. This is a terminal status, the open invoice will be voided and no further invoices will be generated.

  A subscription that is currently in a trial period is trialing and moves to active when the trial period is over.

  A subscription can only enter a paused status when a trial ends without a payment method. A paused subscription doesn’t generate invoices and can be resumed after your customer adds their payment method. The paused status is different from pausing collection, which still generates invoices and leaves the subscription’s status unchanged.

  If subscription collection_method=charge_automatically, it becomes past_due when payment is required but cannot be paid (due to failed payment or awaiting additional user actions). Once Stripe has exhausted all payment retry attempts, the subscription will become canceled or unpaid (depending on your subscriptions settings).

  If subscription collection_method=send_invoice it becomes past_due when its invoice is not paid by the due date, and canceled or unpaid if it is still not paid by an additional deadline after that. Note that when a subscription has a status of unpaid, no subsequent invoices will be attempted (invoices will be created, but then immediately automatically closed). After receiving updated payment information from a customer, you may choose to reopen and pay their closed invoices.

More attributes

Expand all

• objectstring

• applicationnullable stringExpandableConnect only

• application_fee_percentnullable floatConnect only

• billing_cycle_anchortimestamp

• billing_cycle_anchor_confignullable object

• billing_modeobject

• billing_schedulesarray of objects

• billing_thresholdsnullable object

• cancel_atnullable timestamp

• cancel_at_period_endboolean

• canceled_atnullable timestamp

• cancellation_detailsnullable object

• collection_methodenum

• createdtimestamp

• days_until_duenullable integer

• default_sourcenullable stringExpandable

• default_tax_ratesnullable array of objects

• discountsarray of stringsExpandable

• ended_atnullable timestamp

• invoice_settingsobject

• livemodeboolean

• managed_paymentsnullable object

• next_pending_invoice_item_invoicenullable timestamp

• on_behalf_ofnullable stringExpandableConnect only

• pause_collectionnullable object

• payment_settingsnullable object

• pending_invoice_item_intervalnullable object

• presentment_detailsnullable object

• schedulenullable stringExpandable

• start_datetimestamp

• test_clocknullable stringExpandable

• transfer_datanullable objectConnect only

• trial_endnullable timestamp

• trial_settingsnullable object

• trial_startnullable timestamp

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