Attributes

• idstring

  Unique identifier for the object.

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

• priceobject

  The price the customer is subscribed to.

  Show child attributes

• quantitynullable integer

  The quantity of the plan to which the customer should be subscribed.

• subscriptionstring

  The subscription this subscription_item belongs to.

More attributes

Expand all

• objectstring

• billed_untilnullable timestampPreview featureExpandable

• billing_thresholdsnullable object

• createdinteger

• current_period_endtimestamp

• current_period_starttimestamp

• discountsarray of stringsExpandable

• tax_ratesnullable array of objects

Adds a new item to an existing subscription. No existing items will be changed or replaced.

Parameters

• subscriptionstringRequired

  The identifier of the subscription to modify.

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

• pricestring

  The ID of the price object.

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

• quantityinteger

  The quantity you’d like to apply to the subscription item you’re creating.

More parameters

Expand all

• billing_thresholdsobject

• discountsarray of objects

• price_dataobject

• proration_datetimestamp

• tax_ratesarray of strings

Updates the plan or quantity of an item on a current subscription.

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.

• pricestring

  The ID of the price object. One of price or price_data is required. When changing a subscription item’s price, quantity is set to 1 unless a quantity parameter is provided.

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

• quantityinteger

  The quantity you’d like to apply to the subscription item you’re creating.

More parameters

Expand all

• billing_thresholdsobject

• discountsarray of objects

• off_sessionboolean

• price_dataobject

• proration_datetimestamp

• tax_ratesarray of strings

Retrieves the subscription item with the given ID.

Parameters

No parameters.