Update a subscription item

Changed on

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

post/v1/subscription_items/{item}

Request

  • Base URL: https://api.stripe.com
  • URL: https://api.stripe.com/v1/subscription_items/{item}
  • Auth: one of:
    • HTTP basic
    • HTTP bearer

Path parameters

itemstring required

Request body application/x-www-form-urlencoded

expandstring[]

Specifies which fields in the response should be expanded.

off_sessionboolean

Indicates if a customer is on or off-session while an invoice payment is attempted. Defaults to false (on-session).

payment_behavior'allow_incomplete' | 'default_incomplete' | 'error_if_incomplete' | 'pending_if_incomplete'

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

pricestring

The ID of the price object. You can use either price or price_data, but not both, to set or change this item's price. If you're updating an existing item without changing its price, omit both. When changing a subscription item's price, quantity is set to 1 unless a quantity parameter is provided.

proration_behavior'always_invoice' | 'create_prorations' | 'none'

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.

proration_dateinteger

If set, the proration will be calculated as though the subscription was updated at the given time. This can be used to apply the same proration that was previewed with the upcoming invoice endpoint.

quantityinteger

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

Response

Successful response.

billed_untilinteger

The time period the subscription item has been billed for.

createdinteger required

Time at which the object was created. Measured in seconds since the Unix epoch.

current_period_endinteger required

The end time of this subscription item's current billing period.

current_period_startinteger required

The start time of this subscription item's current billing period.

idstring required

Unique identifier for the object.

metadataobject required

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.

object'subscription_item' required

String representing the object's type. Objects of the same type share the same value.

quantityinteger

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

subscriptionstring required

The subscription this subscription_item belongs to.

Changes

  • c113b1939b8fRevision changes
    • info

      added the optional property ////// to the response with the status

  • 7b8f614372caRevision changes
    • info

      added the optional property ////////// to the response with the status

Some revisions have not been checked yet.