Sample - Stripe API
DELETE/v1/subscription_items/{item}

Delete a subscription item

Deletes an item from a subscription without canceling the subscription itself. Use clear_usage when removing a metered item and configure proration_behavior or payment_behavior for any billing changes caused by removal. The response confirms deletion with the removed item's identifier.

  • RetriesRetries up to 2×, 500ms backoff, 30s timeout.

1 parameter · 4 body fields
itemstringrequired
The unique identifier of the subscription item to delete. Must be no longer than 5000 characters.

Optional settings for clearing usage and handling payment and prorations when deleting the subscription item.

clear_usagebooleanoptional
Delete all usage for the given subscription item. Allowed only when the current plan's `usage_type` is `metered`.
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
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.

2 status codes
200Returns a deleted subscription item object containing `deleted: true`, the item's identifier, and its object type.
deletedbooleanrequired
Always true for a deleted object
Allowed:true
idstringrequired
Unique identifier for the object.
objectstringrequired
String representing the object's type. Objects of the same type share the same value.
Allowed:subscription_item
defaultError response.
errorobjectrequired

Error handling

item must be a string no longer than 5000 characters. clear_usage is allowed only when the current plan uses metered usage, and payment_behavior and proration_behavior must use their documented enum values. proration_date must be a Unix timestamp when supplied.