Public preview
Adds the subscription pause endpoint Public preview
What’s new
Adds the pause endpoint to the Subscriptions API. Paused subscriptions have paused status and include a status_details field.
Also adds the payment_behavior parameter to the resume endpoint to control how the subscription resumes:
- resume _ on _ payment _ success Recommended : attempts payment during the resume request. The subscription stays paused until payment succeeds, and Stripe retries failed payments.
- resume _ on _ payment _ attempt Default : no payment attempt during the resume request. If collecting payment on the resumed subscription’s invoice fails (for example with Pay Invoice), the subscription moves to past _ due , and Stripe doesn’t retry failed payments.
Impact
You can now pause an active subscription to suspend both service delivery and invoice generation until you resume it. This gives your customers a temporary alternative to canceling for scenarios like vacations, temporary non-usage, or goodwill holds. This differs from pause payment collection, which keeps access and invoicing running and only pauses collection. Pausing requires flexible billing mode.
You can listen for customer.subscription.paused to revoke service access and customer.subscription.resumed to restore it.
For full integration guidance, including restrictions, events, and code examples, see Pause subscriptions.
Changes
| Endpoint | Change | Resource |
|---|---|---|
| pause | Added | Subscription |
| Parameters | Change | Resources or endpoints |
| payment_behavior | Added | Subscription#resume |
| status_details | Added | Subscription |
Upgrade
- View your current API version in Workbench.
- If you use an SDK, upgrade to the corresponding SDK version for this API version.
- If you don’t use an SDK, update your API requests to include Stripe-Version: 2026-05-27. preview
- Upgrade the API version used for webhook endpoints .
- Test your integration against the new version.
- If you use Connect, test your Connect integration .
- In Workbench, perform the upgrade . You can roll back the version for 72 hours.
Learn more about Stripe API upgrades.