--- title: "Update a subscription item" method: POST path: "/v1/subscription_items/{item}" --- # Update a subscription item `POST /v1/subscription_items/{item}` Updates the plan or quantity of an item on a current subscription. ## Path parameters - `item` string, required ## Response `200` Successful response. - SubscriptionItem — Subscription items allow you to create customer subscriptions with more than one plan, making it easy to represent complex billing relationships. - `billed_until` integer — The time period the subscription item has been billed for. - `billing_thresholds` SubscriptionItemBillingThresholds - `usage_gte` integer, nullable — Usage threshold that triggers the subscription to create an invoice - `created` integer, required — Time at which the object was created. Measured in seconds since the Unix epoch. - `current_period_end` integer, required — The end time of this subscription item's current billing period. - `current_period_start` integer, required — The start time of this subscription item's current billing period. - `discounts` union[], required — The discounts applied to the subscription item. Subscription item discounts are applied before subscription discounts. Use `expand[]=discounts` to expand each discount. - union - string - Discount — A discount represents the actual application of a [coupon](https://api.stripe.com#coupons) or [promotion code](https://api.stripe.com#promotion_codes). It contains information about when the discount began, when it will end, and what it is applied to. Related guide: [Applying discounts to subscriptions](https://docs.stripe.com/billing/subscriptions/discounts) - `checkout_session` string, nullable — The Checkout session that this coupon is applied to, if it is applied to a particular session in payment mode. Not present for subscription mode. - `customer` union — The ID of the customer associated with this discount. - string - Customer — This object represents a customer of your business. Use it to [create recurring charges](https://docs.stripe.com/invoicing/customer), [save payment](https://docs.stripe.com/payments/save-during-payment) and contact information, and track payments that belong to the same customer. - `address` Address - … - `balance` integer — The current balance, if any, that's stored on the customer in their default currency. If negative, the customer has credit to apply to their next invoice. If positive, the customer has an amount owed that's added to their next invoice. The balance only considers amounts that Stripe hasn't successfully applied to any invoice. It doesn't reflect unpaid invoices. This balance is only taken into account after invoices finalize. For multi-currency balances, see [invoice_credit_balance](https://docs.stripe.com/api/customers/object#customer_object-invoice_credit_balance). - `business_name` string — The customer's business name. - `cash_balance` CashBalance — A customer's `Cash balance` represents real funds. Customers can add funds to their cash balance by sending a bank transfer. These funds can be used for payment and can eventually be paid out to your bank account. - … - `created` integer, required — Time at which the object was created. Measured in seconds since the Unix epoch. - `currency` string, nullable — Three-letter [ISO code for the currency](https://stripe.com/docs/currencies) the customer can be charged in for recurring billing purposes. - `customer_account` string, nullable — The ID of an Account representing a customer. You can use this ID with any v1 API that accepts a customer_account parameter. - `default_source` union — ID of the default payment source for the customer. If you use payment methods created through the PaymentMethods API, see the [invoice_settings.default_payment_method](https://docs.stripe.com/api/customers/object#customer_object-invoice_settings-default_payment_method) field instead. - … - `delinquent` boolean, nullable — Tracks the most recent state change on any invoice belonging to the customer. Paying an invoice or marking it uncollectible via the API will set this field to false. An automatic payment failure or passing the `invoice.due_date` will set this field to `true`. If an invoice becomes uncollectible by [dunning](https://docs.stripe.com/billing/automatic-collection), `delinquent` doesn't reset to `false`. If you care whether the customer has paid their most recent subscription invoice, use `subscription.status` instead. Paying or marking uncollectible any customer invoice regardless of whether it is the latest invoice for a subscription will always set this field to `false`. - `description` string, nullable — An arbitrary string attached to the object. Often useful for displaying to users. - `discount` Discount — recursive - `email` string, nullable — The customer's email address. - `id` string, required — Unique identifier for the object. - `individual_name` string — The customer's individual name. - `invoice_credit_balance` object — The current multi-currency balances, if any, that's stored on the customer. If positive in a currency, the customer has a credit to apply to their next invoice denominated in that currency. If negative, the customer has an amount owed that's added to their next invoice denominated in that currency. These balances don't apply to unpaid invoices. They solely track amounts that Stripe hasn't successfully applied to any invoice. Stripe only applies a balance in a specific currency to an invoice after that invoice (which is in the same currency) finalizes. - `invoice_prefix` string, nullable — The prefix for the customer used to generate unique invoice numbers. - `invoice_settings` InvoiceSettingCustomerSetting - … - `livemode` boolean, required — If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`. - `metadata` object — 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. - `name` string, nullable — The customer's full name or business name. - `next_invoice_sequence` integer — The suffix of the customer's next invoice number (for example, 0001). When the account uses account level sequencing, this parameter is ignored in API requests and the field omitted in API responses. - `object` 'customer', required — String representing the object's type. Objects of the same type share the same value. - `phone` string, nullable — The customer's phone number. - `preferred_locales` string[], nullable — The customer's preferred locales (languages), ordered by preference. - `shipping` Shipping - … - `sources` object — The customer's payment sources, if any. - … - `subscriptions` object — The customer's current subscriptions, if any. - … - `tax` CustomerTax - … - `tax_exempt` 'exempt' | 'none' | 'reverse', nullable — Describes the customer's tax exemption status, which is `none`, `exempt`, or `reverse`. When set to `reverse`, invoice and receipt PDFs include the following text: **"Reverse charge"**. - `tax_ids` object — The customer's tax IDs. - … - `test_clock` union — ID of the test clock that this customer belongs to. - … - DeletedCustomer - `deleted` true, required — Always true for a deleted object - `id` string, required — Unique identifier for the object. - `object` 'customer', required — String representing the object's type. Objects of the same type share the same value. - `customer_account` string, nullable — The ID of the account representing the customer associated with this discount. - `end` integer, nullable — If the coupon has a duration of `repeating`, the date that this discount will end. If the coupon has a duration of `once` or `forever`, this attribute will be null. - `id` string, required — The ID of the discount object. Discounts can't be fetched by ID. Use `expand[]=discounts` in API calls to expand discount IDs in an array. - `invoice` string, nullable — The invoice that the discount's coupon was applied to, if it was applied directly to a particular invoice. - `invoice_item` string, nullable — The invoice item `id` (or invoice line item `id` for invoice line items of type='subscription') that the discount's coupon was applied to, if it was applied directly to a particular invoice item or invoice line item. - `object` 'discount', required — String representing the object's type. Objects of the same type share the same value. - `promotion_code` union — The promotion code applied to create this discount. - string - PromotionCode — A Promotion Code represents a customer-redeemable code for an underlying promotion. You can create multiple codes for a single promotion. If you enable promotion codes in your [customer portal configuration](https://docs.stripe.com/customer-management/configure-portal), then customers can redeem a code themselves when updating a subscription in the portal. Customers can also view the currently active promotion codes and coupons on each of their subscriptions in the portal. - `active` boolean, required — Whether the promotion code is currently active. A promotion code is only active if the coupon is also valid. - `code` string, required — The customer-facing code. Regardless of case, this code must be unique across all active promotion codes for each customer. Valid characters are lower case letters (a-z), upper case letters (A-Z), digits (0-9), and dashes (-). - `created` integer, required — Time at which the object was created. Measured in seconds since the Unix epoch. - `customer` union — The customer who can use this promotion code. - … - `customer_account` string, nullable — The account representing the customer who can use this promotion code. - `expires_at` integer, nullable — Date at which the promotion code can no longer be redeemed. - `id` string, required — Unique identifier for the object. - `livemode` boolean, required — If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`. - `max_redemptions` integer, nullable — Maximum number of times this promotion code can be redeemed. - `metadata` object, nullable — 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. - `object` 'promotion_code', required — String representing the object's type. Objects of the same type share the same value. - `promotion` PromotionCodesResourcePromotion, required - … - `restrictions` PromotionCodesResourceRestrictions, required - … - `times_redeemed` integer, required — Number of times this promotion code has been used. - `source` DiscountSource, required - `coupon` union — The coupon that was redeemed to create this discount. - string - Coupon — A coupon contains information about a percent-off or amount-off discount you might want to apply to a customer. Coupons may be applied to [subscriptions](https://api.stripe.com#subscriptions), [invoices](https://api.stripe.com#invoices), [checkout sessions](https://docs.stripe.com/api/checkout/sessions), [quotes](https://api.stripe.com#quotes), and more. Coupons do not work with conventional one-off [charges](/api/charges/create) or [payment intents](https://docs.stripe.com/api/payment_intents). - … - `type` 'coupon', required — The source type of the discount. - `start` integer, required — Date that the coupon was applied. - `subscription` string, nullable — The subscription that this coupon is applied to, if it is applied to a particular subscription. - `subscription_item` string, nullable — The subscription item that this coupon is applied to, if it is applied to a particular subscription item. - `id` string, required — Unique identifier for the object. - `metadata` object, required — 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. - `object` 'subscription_item', required — String representing the object's type. Objects of the same type share the same value. - `price` Price, required — 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). - `active` boolean, required — Whether the price can be used for new purchases. - `billing_scheme` 'per_unit' | 'tiered', required — Describes how to compute the price per period. Either `per_unit` or `tiered`. `per_unit` indicates that the fixed amount (specified in `unit_amount` or `unit_amount_decimal`) will be charged per unit in `quantity` (for prices with `usage_type=licensed`), or per unit of total usage (for prices with `usage_type=metered`). `tiered` indicates that the unit pricing will be computed using a tiering strategy as defined using the `tiers` and `tiers_mode` attributes. - `created` integer, required — Time at which the object was created. Measured in seconds since the Unix epoch. - `currency` string, currency, required — Three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html), in lowercase. Must be a [supported currency](https://stripe.com/docs/currencies). - `currency_options` object — Prices defined in each available currency option. Each key must be a three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) and a [supported currency](https://stripe.com/docs/currencies). - `custom_unit_amount` CustomUnitAmount - `maximum` integer, nullable — The maximum unit amount the customer can specify for this item. - `minimum` integer, nullable — The minimum unit amount the customer can specify for this item. Must be at least the minimum charge amount. - `preset` integer, nullable — The starting unit amount which can be updated by the customer. - `id` string, required — Unique identifier for the object. - `livemode` boolean, required — If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`. - `lookup_key` string, nullable — A lookup key used to retrieve prices dynamically from a static string. This may be up to 200 characters. - `metadata` object, required — 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. - `nickname` string, nullable — A brief description of the price, hidden from customers. - `object` 'price', required — String representing the object's type. Objects of the same type share the same value. - `product` union, required — The ID of the product this price is associated with. - string - Product — Products describe the specific goods or services you offer to your customers. For example, you might offer a Standard and Premium version of your goods or service; each version would be a separate Product. They can be used in conjunction with [Prices](https://api.stripe.com#prices) to configure pricing in Payment Links, Checkout, and Subscriptions. Related guides: [Set up a subscription](https://docs.stripe.com/billing/subscriptions/set-up-subscription), [share a Payment Link](https://docs.stripe.com/payment-links), [accept payments with Checkout](https://docs.stripe.com/payments/accept-a-payment#create-product-prices-upfront), and more about [Products and Prices](https://docs.stripe.com/products-prices/overview) - `active` boolean, required — Whether the product is currently available for purchase. - `created` integer, required — Time at which the object was created. Measured in seconds since the Unix epoch. - `default_price` union — The ID of the [Price](https://docs.stripe.com/api/prices) object that is the default price for this product. - string - Price — recursive - `description` string, nullable — The product's description, meant to be displayable to the customer. Use this field to optionally store a long form explanation of the product being sold for your own rendering purposes. - `id` string, required — Unique identifier for the object. - `images` string[], required — A list of up to 8 URLs of images for this product, meant to be displayable to the customer. - `livemode` boolean, required — If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`. - `marketing_features` ProductMarketingFeature[], required — A list of up to 15 marketing features for this product. These are displayed in [pricing tables](https://docs.stripe.com/payments/checkout/pricing-table). - `name` string — The marketing feature name. Up to 80 characters long. - `metadata` object, required — 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. - `name` string, required — The product's name, meant to be displayable to the customer. - `object` 'product', required — String representing the object's type. Objects of the same type share the same value. - `package_dimensions` PackageDimensions - `height` number, required — Height, in inches. - `length` number, required — Length, in inches. - `weight` number, required — Weight, in ounces. - `width` number, required — Width, in inches. - `shippable` boolean, nullable — Whether this product is shipped (i.e., physical goods). - `statement_descriptor` string, nullable — Extra information about a product which will appear on your customer's credit card statement. In the case that multiple products are billed at once, the first statement descriptor will be used. Only used for subscription payments. - `tax_code` union — A [tax code](https://docs.stripe.com/tax/tax-categories) ID. - string - TaxCode — [Tax codes](https://stripe.com/docs/tax/tax-categories) classify goods and services for tax purposes. - `description` string, required — A detailed description of which types of products the tax code represents. - `id` string, required — Unique identifier for the object. - `name` string, required — A short name for the tax code. - `object` 'tax_code', required — String representing the object's type. Objects of the same type share the same value. - `unit_label` string, nullable — A label that represents units of this product. When set, this will be included in customers' receipts, invoices, Checkout, and the customer portal. - `updated` integer, required — Time at which the object was last updated. Measured in seconds since the Unix epoch. - `url` string, nullable — A URL of a publicly-accessible webpage for this product. - DeletedProduct - `deleted` true, required — Always true for a deleted object - `id` string, required — Unique identifier for the object. - `object` 'product', required — String representing the object's type. Objects of the same type share the same value. - `recurring` Recurring - `interval` 'day' | 'month' | 'week' | 'year', required — The frequency at which a subscription is billed. One of `day`, `week`, `month` or `year`. - `interval_count` integer, required — The number of intervals (specified in the `interval` attribute) between subscription billings. For example, `interval=month` and `interval_count=3` bills every 3 months. - `meter` string, nullable — The meter tracking the usage of a metered price - `usage_type` 'licensed' | 'metered', required — Configures how the quantity per period should be determined. Can be either `metered` or `licensed`. `licensed` automatically bills the `quantity` set when adding it to a subscription. `metered` aggregates the total usage based on usage records. Defaults to `licensed`. - `tax_behavior` 'exclusive' | 'inclusive' | 'unspecified', nullable — Only required if a [default tax behavior](https://docs.stripe.com/tax/products-prices-tax-categories-tax-behavior#setting-a-default-tax-behavior-(recommended)) was not provided in the Stripe Tax settings. Specifies whether the price is considered inclusive of taxes or exclusive of taxes. One of `inclusive`, `exclusive`, or `unspecified`. Once specified as either `inclusive` or `exclusive`, it cannot be changed. - `tiers` PriceTier[] — Each element represents a pricing tier. This parameter requires `billing_scheme` to be set to `tiered`. See also the documentation for `billing_scheme`. - `flat_amount` integer, nullable — Price for the entire tier. - `flat_amount_decimal` string, decimal, nullable — Same as `flat_amount`, but contains a decimal value with at most 12 decimal places. - `unit_amount` integer, nullable — Per unit price for units relevant to the tier. - `unit_amount_decimal` string, decimal, nullable — Same as `unit_amount`, but contains a decimal value with at most 12 decimal places. - `up_to` integer, nullable — Up to and including to this quantity will be contained in the tier. - `tiers_mode` 'graduated' | 'volume', nullable — Defines if the tiering price should be `graduated` or `volume` based. In `volume`-based tiering, the maximum quantity within a period determines the per unit price. In `graduated` tiering, pricing can change as the quantity grows. - `transform_quantity` TransformQuantity - `divide_by` integer, required — Divide usage by this number. - `round` 'down' | 'up', required — After division, either round the result `up` or `down`. - `type` 'one_time' | 'recurring', required — One of `one_time` or `recurring` depending on whether the price is for a one-time purchase or a recurring (subscription) purchase. - `unit_amount` integer, nullable — The unit amount in cents (or local equivalent) to be charged, represented as a whole integer if possible. Only set if `billing_scheme=per_unit`. - `unit_amount_decimal` string, decimal, nullable — The unit amount in cents (or local equivalent) to be charged, represented as a decimal string with at most 12 decimal places. Only set if `billing_scheme=per_unit`. - `quantity` integer — The [quantity](https://docs.stripe.com/subscriptions/quantities) of the plan to which the customer should be subscribed. - `subscription` string, required — The `subscription` this `subscription_item` belongs to. - `tax_rates` TaxRate[], nullable — 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`. - `active` boolean, required — Defaults to `true`. When set to `false`, this tax rate cannot be used with new applications or Checkout Sessions, but will still work for subscriptions and invoices that already have it set. - `country` string, nullable — Two-letter country code ([ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)). - `created` integer, required — Time at which the object was created. Measured in seconds since the Unix epoch. - `description` string, nullable — An arbitrary string attached to the tax rate for your internal use only. It will not be visible to your customers. - `display_name` string, required — The display name of the tax rates as it will appear to your customer on their receipt email, PDF, and the hosted invoice page. - `effective_percentage` number, nullable — Actual/effective tax rate percentage out of 100. For tax calculations with automatic_tax[enabled]=true, this percentage reflects the rate actually used to calculate tax based on the product's taxability and whether the user is registered to collect taxes in the corresponding jurisdiction. - `flat_amount` TaxRateFlatAmount — The amount of the tax rate when the `rate_type`` is `flat_amount`. Tax rates with `rate_type` `percentage` can vary based on the transaction, resulting in this field being `null`. This field exposes the amount and currency of the flat tax rate. - `amount` integer, required — Amount of the tax when the `rate_type` is `flat_amount`. This positive integer represents how much to charge in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). The amount value supports up to eight digits (e.g., a value of 99999999 for a USD charge of $999,999.99). - `currency` string, required — Three-letter ISO currency code, in lowercase. - `id` string, required — Unique identifier for the object. - `inclusive` boolean, required — This specifies if the tax rate is inclusive or exclusive. - `jurisdiction` string, nullable — The jurisdiction for the tax rate. You can use this label field for tax reporting purposes. It also appears on your customer’s invoice. - `jurisdiction_level` 'city' | 'country' | 'county' | 'district' | 'multiple' | 'state', nullable — The level of the jurisdiction that imposes this tax rate. Will be `null` for manually defined tax rates. - `livemode` boolean, required — If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`. - `metadata` object, nullable — 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. - `object` 'tax_rate', required — String representing the object's type. Objects of the same type share the same value. - `percentage` number, required — Tax rate percentage out of 100. For tax calculations with automatic_tax[enabled]=true, this percentage includes the statutory tax rate of non-taxable jurisdictions. - `rate_type` 'flat_amount' | 'percentage', nullable — Indicates the type of tax rate applied to the taxable amount. This value can be `null` when no tax applies to the location. This field is only present for TaxRates created by Stripe Tax. - `state` string, nullable — [ISO 3166-2 subdivision code](https://en.wikipedia.org/wiki/ISO_3166-2), without country prefix. For example, "NY" for New York, United States. - `tax_type` 'amusement_tax' | 'communications_tax' | 'gst' | 'hst' | 'igst' | 'jct' | 'lease_tax' | 'mass_transit_parking_tax' | 'parking_tax' | 'pst' | 'qst' | 'retail_delivery_fee' | 'rst' | 'sales_tax' | 'service_tax' | 'vat', nullable — The high-level tax type, such as `vat` or `sales_tax`. ## Other responses - `default` — Error response. --- [API](https://skmtc.net/stripe/apis/stripe-api-2.md) · [All operations](https://skmtc.net/stripe/apis/stripe-api-2/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/stripe/stripe-api-2/versions/3653ad45bbec/schema)