# Update a subscription item Updates the plan or quantity of an item on a current subscription. ## Request ```curl curl https://api.stripe.com/v1/subscription_items/{{SUBSCRIPTION_ITEM_ID}} \ -u "<>" \ -d "metadata[order_id]=6735" ``` ### Response ```json { "id": "si_NcLYdDxLHxlFo7", "object": "subscription_item", "created": 1680126546, "metadata": { "order_id": "6735" }, "price": { "id": "price_1Mr6rdLkdIwHu7ixwPmiybbR", "object": "price", "active": true, "billing_scheme": "per_unit", "created": 1680126545, "currency": "usd", "custom_unit_amount": null, "discounts": null, "livemode": false, "lookup_key": null, "metadata": {}, "nickname": null, "product": "prod_NcLYGKH0eY5b8s", "recurring": { "interval": "month", "interval_count": 1, "trial_period_days": null, "usage_type": "licensed" }, "tax_behavior": "unspecified", "tiers_mode": null, "transform_quantity": null, "type": "recurring", "unit_amount": 1000, "unit_amount_decimal": "1000" }, "quantity": 2, "subscription": "sub_1Mr6rbLkdIwHu7ix4Xm9Ahtd", "tax_rates": [] } ``` ## Returns ## Parameters - [`billing_thresholds`](https://docs.stripe.com/api/subscription_items/update.md?query=billing_thresholds) (object, optional) Define thresholds at which an invoice will be sent, and the subscription advanced to a new billing period. Pass an empty string to remove previously-defined thresholds. - [`discounts`](https://docs.stripe.com/api/subscription_items/update.md?query=discounts) (array of objects, optional) The coupons to redeem into discounts for the subscription item. - `metadata` (map, optional) Set of [key-value pairs](https://docs.stripe.com/api/metadata.md) 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`. - `off_session` (boolean, optional) Indicates if a customer is on or off-session while an invoice payment is attempted. Defaults to `false` (on-session). - `payment_behavior` (enum, optional) 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](changelog/2019-03-14/subscriptions-successfully-created-first-payment-fails). 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](https://docs.stripe.com/billing/migration/strong-customer-authentication.md) 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](https://docs.stripe.com/api/invoices/object.md#invoice_object-auto_advance), 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](changelog/2019-03-14/subscriptions-successfully-created-first-payment-fails). - `pending_if_incomplete` If payment fails, Stripe creates a [pending update](https://docs.stripe.com/billing/subscriptions/pending-updates.md), which applies only if the payment eventually succeeds. This behavior doesn’t support all [attributes and payment methods](https://docs.stripe.com/billing/pending-updates-reference.md#supported-attributes). This option is the simplest way to ensure the customer completes payment before Stripe applies the update. - `price` (string, optional) 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. - [`price_data`](https://docs.stripe.com/api/subscription_items/update.md?query=price_data) (object, optional) Data used to generate a new [Price](https://docs.stripe.com/api/prices.md) object inline. One of `price` or `price_data` is required. - `proration_behavior` (enum, optional) Determines how to handle [prorations](https://docs.stripe.com/billing/subscriptions/prorations.md) 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](https://docs.stripe.com/subscriptions/upgrading-downgrading.md#immediate-payment). - `none` Disable creating prorations in this request. - `proration_date` (timestamp, optional) 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](https://docs.stripe.com/api/invoices/create_preview.md) endpoint. - `quantity` (integer, optional) The quantity you’d like to apply to the subscription item you’re creating. - `tax_rates` (array of strings, optional) A list of [Tax Rate](https://docs.stripe.com/api/tax_rates.md) ids. These Tax Rates will override the [`default_tax_rates`](https://docs.stripe.com/api/subscriptions/create.md#create_subscription-default_tax_rates) on the Subscription. When updating, pass an empty string to remove previously-defined tax rates.