Retrieve a subscription item

GET / v1 / subscription_items /:id

Retrieves the subscription item with the given ID.

Parameters

No parameters.

Returns

Returns a subscription item if a valid subscription item ID was provided. Raises an error otherwise.

Response

{ "id": "si_NcLYdDxLHxlFo7", "object": "subscription_item", "created": 1680126546, "metadata": {}, "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": []}

List all subscription items

GET / v1 / subscription_items

Returns a list of your subscription items for a given subscription.

Parameters

• subscription string Required The ID of the subscription whose items will be retrieved.

More parameters

• ending _ before string
• limit integer
• starting _ after string

Returns

A dictionary with a data property that contains an array of up to limit subscription items, starting after subscription item starting_after. Each entry in the array is a separate subscription item object. If no more subscription items are available, the resulting array will be empty.

Response

{ "object": "list", "url": "/v1/subscription_items", "has_more": false, "data": [ { "id": "si_OCgWsGlqpbN4EP", "object": "subscription_item", "created": 1688507587, "metadata": {}, "price": { "id": "price_1NQH9iLkdIwHu7ix3tkaSxhj", "object": "price", "active": true, "billing_scheme": "per_unit", "created": 1688507586, "currency": "usd", "custom_unit_amount": null, "livemode": false, "lookup_key": null, "metadata": {}, "nickname": null, "product": "prod_OCgWE6cbwiSu27", "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": 1, "subscription": "sub_1NQH9iLkdIwHu7ixxhHui9yi", "tax_rates": [] } ]}

Delete a subscription item

DELETE / v1 / subscription_items /:id

Deletes an item from the subscription. Removing a subscription item from a subscription will not cancel the subscription.

Parameters

• payment _ behavior enum 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. 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 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, 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. To handle payments that require action, use allow_incomplete or default_incomplete instead. This behavior was the default for API versions before 2019-03-14. pending_if_incomplete If payment fails, Stripe creates a pending update, which applies only if the payment eventually succeeds. This behavior doesn’t support all attributes and payment methods. This option is the simplest way to ensure the customer completes payment before Stripe applies the update.
• proration _ behavior enum Determines how to handle 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. 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. none Disable creating prorations in this request.

More parameters

• clear _ usage boolean
• proration _ date timestamp

Returns

An subscription item object with a deleted flag upon success. Otherwise, this call raises an error, such as if the subscription item has already been deleted.

Response

{ "id": "si_NcLYdDxLHxlFo7", "object": "subscription_item", "deleted": true}