Pauses a subscription by transitioning it to the paused status. A paused subscription does not generate invoices and will not advance to new billing periods. The subscription can be resumed later using the resume endpoint. Cannot pause subscriptions with attached schedules.
Parameters
- bill_
forobject Controls what to bill for when pausing the subscription.
- invoicing_
behaviorenum Determines how to handle debits and credits when pausing. Defaults to
pending_.invoice_ item Possible enum valuesinvoiceInvoices immediately for debits and credits in the current period. If pausing doesn’t create any invoice items, Stripe doesn’t generate an invoice.
pending_invoice_ item Creates pending invoice items for debits and credits in the current period.
- typeenum
The type of pause to apply. Defaults to
subscription.Possible enum valuessubscriptionPauses collection, billing, and servicing.
More parameters
- idstringRequired
Returns
The subscription object.
curl https://api.stripe.com/v1/subscriptions/{{SUBSCRIPTION_ID}}/pause \ -u "sk_test_...sk_test_...:" \ -H "Stripe-Version: 2026-10-28.endive" \ -d type=subscription{ "id": "sub_1MoGGtLkdIwHu7ixk5CfdiqC", "object": "subscription", "application": null, "application_fee_percent": null, "automatic_tax": { "enabled": false, "liability": null }, "billing_cycle_anchor": 1679447726, "cancel_at": null, "cancel_at_period_end": false, "canceled_at": null, "cancellation_details": { "comment": null, "feedback": null, "reason": null }, "collection_method": "charge_automatically", "created": 1679447723, "currency": "usd", "customer": "cus_NZP5i1diUz55jp", "days_until_due": null, "default_payment_method": null, "default_source": null, "default_tax_rates": [], "description": null, "discounts": null, "ended_at": null, "invoice_settings": { "issuer": { "type": "self" } }, "items": { "object": "list", "data": [ { "id": "si_NZP5BhUIuWzXDG", "object": "subscription_item", "created": 1679447724, "current_period_end": 1682126126, "current_period_start": 1679447726, "current_trial": null, "metadata": {}, "plan": { "id": "price_1MoGGsLkdIwHu7ixA9yHsq2N", "object": "plan", "active": true, "amount": 1099, "amount_decimal": "1099", "billing_scheme": "per_unit", "created": 1679447722, "currency": "usd", "interval": "month", "interval_count": 1, "livemode": false, "metadata": {}, "nickname": null, "product": "prod_NZP5rEATBlScM9", "tiers_mode": null, "transform_usage": null, "trial_period_days": null, "usage_type": "licensed" }, "price": { "id": "price_1MoGGsLkdIwHu7ixA9yHsq2N", "object": "price", "active": true, "billing_scheme": "per_unit", "created": 1679447722, "currency": "usd", "custom_unit_amount": null, "livemode": false, "lookup_key": null, "metadata": {}, "nickname": null, "product": "prod_NZP5rEATBlScM9", "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": 1099, "unit_amount_decimal": "1099" }, "quantity": 1, "subscription": "sub_1MoGGtLkdIwHu7ixk5CfdiqC", "tax_rates": [] } ], "has_more": false, "total_count": 1, "url": "/v1/subscription_items?subscription=sub_1MoGGtLkdIwHu7ixk5CfdiqC" }, "latest_invoice": "in_1MoGGwLkdIwHu7ixHSrelo8X", "livemode": false, "metadata": {}, "next_pending_invoice_item_invoice": null, "on_behalf_of": null, "pause_collection": null, "payment_settings": { "payment_method_options": null, "payment_method_types": null, "save_default_payment_method": "off" }, "pending_invoice_item_interval": null, "pending_setup_intent": null, "pending_update": null, "plan": { "id": "price_1MoGGsLkdIwHu7ixA9yHsq2N", "object": "plan", "active": true, "amount": 1099, "amount_decimal": "1099", "billing_scheme": "per_unit", "created": 1679447722, "currency": "usd", "interval": "month", "interval_count": 1, "livemode": false, "metadata": {}, "nickname": null, "product": "prod_NZP5rEATBlScM9", "tiers_mode": null, "transform_usage": null, "trial_period_days": null, "usage_type": "licensed" }, "quantity": 1, "schedule": null, "start_date": 1679447723, "status": "paused", "test_clock": null, "transfer_data": null, "trial_end": null, "trial_settings": { "end_behavior": { "missing_payment_method": "create_invoice", "billing_cycle_anchor": "now" } }, "trial_start": null}Initiates resumption of a paused subscription, optionally resetting the billing cycle anchor and creating prorations. Resume is only available for subscriptions that use charge_ collection. If Stripe doesn’t generate a resumption invoice, the subscription becomes active immediately. When a resumption invoice is generated, Stripe finalizes it immediately. If the invoice is paid or marked uncollectible, the subscription becomes active. If the invoice is manually voided, the subscription stays paused. If there is no payment attempt within 23 hours, Stripe voids the invoice and the subscription stays paused. Learn more about resuming subscriptions.
Parameters
- billing_
cycle_ anchorobject The billing cycle anchor that applies when the subscription is resumed. Either
noworunchanged. The default isnow. For more information, see the billing cycle documentation. - proration_
behaviorenum Determines how to handle prorations resulting from the
billing_beingcycle_ anchor unchanged. When thebilling_is set tocycle_ anchor now(default value), no prorations are generated. If no value is passed, the default iscreate_.prorations Possible enum valuesalways_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.
noneDisable creating prorations in this request.
More parameters
- idstringRequired
- payment_
behaviorenum - proration_
datetimestamp
Returns
The subscription object.
curl https://api.stripe.com/v1/subscriptions/{{SUBSCRIPTION_ID}}/resume \ -u "sk_test_...sk_test_...:" \ -H "Stripe-Version: 2026-10-28.endive" \ -d "billing_cycle_anchor[type]=now"{ "id": "sub_1MoGGtLkdIwHu7ixk5CfdiqC", "object": "subscription", "application": null, "application_fee_percent": null, "automatic_tax": { "enabled": false, "liability": null }, "billing_cycle_anchor": 1679447726, "cancel_at": null, "cancel_at_period_end": false, "canceled_at": null, "cancellation_details": { "comment": null, "feedback": null, "reason": null }, "collection_method": "charge_automatically", "created": 1679447723, "currency": "usd", "customer": "cus_NZP5i1diUz55jp", "days_until_due": null, "default_payment_method": null, "default_source": null, "default_tax_rates": [], "description": null, "discounts": null, "ended_at": null, "invoice_settings": { "issuer": { "type": "self" } }, "items": { "object": "list", "data": [ { "id": "si_NZP5BhUIuWzXDG", "object": "subscription_item", "created": 1679447724, "current_period_end": 1682126126, "current_period_start": 1679447726, "current_trial": null, "metadata": {}, "plan": { "id": "price_1MoGGsLkdIwHu7ixA9yHsq2N", "object": "plan", "active": true, "amount": 1099, "amount_decimal": "1099", "billing_scheme": "per_unit", "created": 1679447722, "currency": "usd", "interval": "month", "interval_count": 1, "livemode": false, "metadata": {}, "nickname": null, "product": "prod_NZP5rEATBlScM9", "tiers_mode": null, "transform_usage": null, "trial_period_days": null, "usage_type": "licensed" }, "price": { "id": "price_1MoGGsLkdIwHu7ixA9yHsq2N", "object": "price", "active": true, "billing_scheme": "per_unit", "created": 1679447722, "currency": "usd", "custom_unit_amount": null, "livemode": false, "lookup_key": null, "metadata": {}, "nickname": null, "product": "prod_NZP5rEATBlScM9", "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": 1099, "unit_amount_decimal": "1099" }, "quantity": 1, "subscription": "sub_1MoGGtLkdIwHu7ixk5CfdiqC", "tax_rates": [] } ], "has_more": false, "total_count": 1, "url": "/v1/subscription_items?subscription=sub_1MoGGtLkdIwHu7ixk5CfdiqC" }, "latest_invoice": "in_1MoGGwLkdIwHu7ixHSrelo8X", "livemode": false, "metadata": {}, "next_pending_invoice_item_invoice": null, "on_behalf_of": null, "pause_collection": null, "payment_settings": { "payment_method_options": null, "payment_method_types": null, "save_default_payment_method": "off" }, "pending_invoice_item_interval": null, "pending_setup_intent": null, "pending_update": null, "plan": { "id": "price_1MoGGsLkdIwHu7ixA9yHsq2N", "object": "plan", "active": true, "amount": 1099, "amount_decimal": "1099", "billing_scheme": "per_unit", "created": 1679447722, "currency": "usd", "interval": "month", "interval_count": 1, "livemode": false, "metadata": {}, "nickname": null, "product": "prod_NZP5rEATBlScM9", "tiers_mode": null, "transform_usage": null, "trial_period_days": null, "usage_type": "licensed" }, "quantity": 1, "schedule": null, "start_date": 1679447723, "status": "active", "test_clock": null, "transfer_data": null, "trial_end": null, "trial_settings": { "end_behavior": { "missing_payment_method": "create_invoice", "billing_cycle_anchor": "now" } }, "trial_start": null}Search for subscriptions you’ve previously created using Stripe’s Search Query Language. Don’t use search in read-after-write flows where strict consistency is necessary. Under normal operating conditions, data is searchable in less than a minute. Occasionally, propagation of new or updated data can be up to an hour behind during outages. Search functionality is not available to merchants in India.
Parameters
- querystringRequired
The search query string. See search query language and the list of supported query fields for subscriptions.
- limitinteger
A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.
- pagestring
A cursor for pagination across multiple pages of results. Don’t include this parameter on the first call. Use the next_page value returned in a previous response to request subsequent results.
Returns
A dictionary with a data property that contains an array of up to limit subscriptions. If no objects match the query, the resulting array will be empty. See the related guide on expanding properties in lists.
{ "object": "search_result", "url": "/v1/subscriptions/search", "has_more": false, "data": [ { "id": "sub_1MoG3CLkdIwHu7ixd86qvAfe", "object": "subscription", "application": null, "application_fee_percent": null, "automatic_tax": { "enabled": false, "liability": null }, "billing_cycle_anchor": 1679446874, "cancel_at": null, "cancel_at_period_end": false, "canceled_at": null, "cancellation_details": { "comment": null, "feedback": null, "reason": null }, "collection_method": "charge_automatically", "created": 1679446874, "currency": "usd", "customer": "cus_NZOq6LNU39H6ZI", "days_until_due": null, "default_payment_method": null, "default_source": null, "default_tax_rates": [], "description": null, "discounts": null, "ended_at": null, "invoice_settings": { "issuer": { "type": "self" } }, "items": { "object": "list", "data": [ { "id": "si_NZOqmziODmZt2v", "object": "subscription_item", "created": 1679446875, "current_period_end": 1682125274, "current_period_start": 1679446874, "current_trial": null, "metadata": {}, "plan": { "id": "price_1MoG3BLkdIwHu7ixrHMcmj3f", "object": "plan", "active": true, "amount": 1099, "amount_decimal": "1099", "billing_scheme": "per_unit", "created": 1679446873, "currency": "usd", "interval": "month", "interval_count": 1, "livemode": false, "metadata": {}, "nickname": null, "product": "prod_NZOqsBJfaRYI1M", "tiers_mode": null, "transform_usage": null, "trial_period_days": null, "usage_type": "licensed" }, "price": { "id": "price_1MoG3BLkdIwHu7ixrHMcmj3f", "object": "price", "active": true, "billing_scheme": "per_unit", "created": 1679446873, "currency": "usd", "custom_unit_amount": null, "livemode": false, "lookup_key": null, "metadata": {}, "nickname": null, "product": "prod_NZOqsBJfaRYI1M", "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": 1099, "unit_amount_decimal": "1099" }, "quantity": 1, "subscription": "sub_1MoG3CLkdIwHu7ixd86qvAfe", "tax_rates": [] } ], "has_more": false, "total_count": 1, "url": "/v1/subscription_items?subscription=sub_1MoG3CLkdIwHu7ixd86qvAfe" }, "latest_invoice": "in_1MoG3CLkdIwHu7ixuBm2QIyW", "livemode": false, "metadata": { "order_id": "6735" }, "next_pending_invoice_item_invoice": null, "on_behalf_of": null, "pause_collection": null, "payment_settings": { "payment_method_options": null, "payment_method_types": null, "save_default_payment_method": "off" }, "pending_invoice_item_interval": null, "pending_setup_intent": null, "pending_update": null, "plan": { "id": "price_1MoG3BLkdIwHu7ixrHMcmj3f", "object": "plan", "active": true, "amount": 1099, "amount_decimal": "1099", "billing_scheme": "per_unit", "created": 1679446873, "currency": "usd", "interval": "month", "interval_count": 1, "livemode": false, "metadata": {}, "nickname": null, "product": "prod_NZOqsBJfaRYI1M", "tiers_mode": null, "transform_usage": null, "trial_period_days": null, "usage_type": "licensed" }, "quantity": 1, "schedule": null, "start_date": 1679446874, "status": "active", "test_clock": null, "transfer_data": null, "trial_end": null, "trial_settings": { "end_behavior": { "missing_payment_method": "create_invoice", "billing_cycle_anchor": "now" } }, "trial_start": null } ]}