Attributes

• idstring

  Unique identifier for the object.

• metadatamap

  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 timestampExpandable

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

• metadatamap

  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 Invoices PaymentIntent. The resulting Invoice has auto_advance=false, so Stripe doesnt automatically attempt payment, retry payment, or finalize the subscription.

  error_if_incomplete If payment fails, return an HTTP 402 status code and dont update the subscription. This behavior doesnt 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 doesnt 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 items 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 youd like to apply to the subscription item youre creating.

More parameters

Expand all

• billing_thresholdsobject

• discountsarray of objects

• price_dataobject

• proration_datetimestamp

• tax_ratesarray of strings