Sample - Stripe API
POST/v1/subscription_items

Create a subscription item

Adds a new item to an existing subscription. No existing items will be changed or replaced.

  • RetriesRetries up to 2×, 500ms backoff, 30s timeout.
  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

12 body fields
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`.
payment_behaviorstringoptional
Controls how Stripe handles payment when a subscription update requires payment and `collection_method=charge_automatically`.
Allowed:allow_incompletedefault_incompleteerror_if_incompletepending_if_incomplete
pricestringoptional
The ID of the price object.
price_dataobjectoptional
Data used to generate a new [Price](https://docs.stripe.com/api/prices) object inline.
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`.
Allowed:always_invoicecreate_prorationsnone
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.
subscriptionstringrequired
The identifier of the subscription to modify.
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.

2 status codes
200Successful response.
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.
Allowed:subscription_item
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

Any other status is an error: Error response.