The Subscription Item object

Attributes

id string Unique identifier for the object.
metadata map Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
price object The price the customer is subscribed to.
quantity nullable integer The quantity of the plan to which the customer should be subscribed.
subscription string The subscription this subscription_item belongs to.

More attributes

object string, value is "subscription_item"
billed _ until nullable timestamp Includable
billing _ thresholds nullable object
created integer
current _ period _ end timestamp
current _ period _ start timestamp
discounts array of strings Expandable
tax _ rates nullable array of objects

{ "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": []}

Create a subscription item

POST / v1 / subscription_items

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

Parameters

subscription string Required The identifier of the subscription to modify.
metadata map Set of key-value pairs 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 _ 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.
price string The ID of the price object.
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.
quantity integer The quantity you’d like to apply to the subscription item you’re creating.

More parameters

billing _ thresholds object
discounts array of objects
price _ data object
proration _ date timestamp
tax _ rates array of strings

Returns

Returns the created Subscription Item object, if successful. Otherwise, this call raises an error.

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": []}

Update a subscription item

POST / v1 / subscription_items /:id

Updates the plan or quantity of an item on a current subscription.

Parameters

metadata map Set of key-value pairs 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 _ 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.
price string 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.
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.
quantity integer The quantity you’d like to apply to the subscription item you’re creating.

More parameters

billing _ thresholds object
discounts array of objects
off _ session boolean
price _ data object
proration _ date timestamp
tax _ rates array of strings

Returns

Response

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