POST
/v1/subscription_items/{item}Update a subscription item
Updates the plan, quantity, billing thresholds, discounts, or tax settings for a subscription item. Supply price or price_data when changing the item's price, and use quantity, proration_behavior, and payment_behavior to control billing changes. The response includes the updated subscription item and its associated price and subscription.
- RetriesRetries up to 2×, 500ms backoff, 30s timeout.
- IdempotentThe SDK sends
Idempotency-Key, so a retried request is only applied once.
itemstringrequired
The unique identifier of the subscription item to update. Must be no longer than 5000 characters.
Subscription item fields to update, including pricing, quantity, discounts, metadata, and tax settings.
billing_thresholdsobjectoptional
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.
discountsarray<DiscountsDataParam>optional
The coupons to redeem into discounts for the subscription item.
expandarray<string>optional
Specifies which fields in the response should be expanded.
metadataobjectoptional
Set of [key-value pairs](https://docs.stripe.com/api/metadata) 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_sessionbooleanoptional
Indicates if a customer is on or off-session while an invoice payment is attempted. Defaults to `false` (on-session).
payment_behaviorstringoptional
Controls how Stripe handles payment when a subscription update requires payment and `collection_method=charge_automatically`.
pricestringoptional
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_dataobjectoptional
Data used to generate a new [Price](https://docs.stripe.com/api/prices) object inline. One of `price` or `price_data` is required.
proration_behaviorstringoptional
Determines how to handle [prorations](https://docs.stripe.com/billing/subscriptions/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_dateintegeroptional
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](/api/invoices/create_preview) endpoint.
quantityintegeroptional
The quantity you'd like to apply to the subscription item you're creating.
tax_ratesarray<string>optional
A list of [Tax Rate](https://docs.stripe.com/api/tax_rates) ids. These Tax Rates will override the [`default_tax_rates`](https://docs.stripe.com/api/subscriptions/create#create_subscription-default_tax_rates) on the Subscription. When updating, pass an empty string to remove previously-defined tax rates.
200Returns the updated subscription item, including its identifier, subscription, quantity, price, billing period, discounts, metadata, and tax rates.
billed_untilintegeroptional
The time period the subscription item has been billed for.
billing_thresholdsobjectoptional
Define thresholds at which an invoice will be sent, and the related subscription advanced to a new billing period
createdintegerrequired
Time at which the object was created. Measured in seconds since the Unix epoch.
current_period_endintegerrequired
The end time of this subscription item's current billing period.
current_period_startintegerrequired
The start time of this subscription item's current billing period.
discountsarray<string>required
The discounts applied to the subscription item. Subscription item discounts are applied before subscription discounts. Use `expand[]=discounts` to expand each discount.
idstringrequired
Unique identifier for the object.
metadataobjectrequired
Set of [key-value pairs](https://docs.stripe.com/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
objectstringrequired
String representing the object's type. Objects of the same type share the same value.
priceobjectrequired
Prices define the unit cost, currency, and (optional) billing cycle for both recurring and one-time purchases of products.
[Products](https://api.stripe.com#products) help you track inventory or provisioning, and prices help you track payment terms. Different physical goods or levels of service should be represented by products, and pricing options should be represented by prices. This approach lets you change prices without having to change your provisioning scheme.
For example, you might have a single "gold" product that has prices for $10/month, $100/year, and €9 once.
Related guides: [Set up a subscription](https://docs.stripe.com/billing/subscriptions/set-up-subscription), [create an invoice](https://docs.stripe.com/billing/invoices/create), and more about [products and prices](https://docs.stripe.com/products-prices/overview).
quantityintegeroptional
The [quantity](https://docs.stripe.com/subscriptions/quantities) of the plan to which the customer should be subscribed.
subscriptionstringrequired
The `subscription` this `subscription_item` belongs to.
tax_ratesarray<TaxRate>optional
The tax rates which apply to this `subscription_item`. When set, the `default_tax_rates` on the subscription do not apply to this `subscription_item`.
defaultError response.
errorobjectrequired
Error handling
item must be a string no longer than 5000 characters. Supply one of price or price_data; when using price_data, currency, product, and recurring are required. Enum fields must use the documented values, including payment_behavior, proration_behavior, and price_data.tax_behavior.