Stripe Subscriptions API adds pause and configurable resume behavior

Introduced 2026-05-27 · score 0.98

HOW TO USE IT

For an active subscription using flexible billing mode, call the pause endpoint to suspend service and invoice generation. Revoke access on `customer.subscription.paused`, restore it on `customer.subscription.resumed`, and choose the resume payment behavior.

curl https://api.stripe.com/v1/subscriptions/<SUBSCRIPTION_ID>/pause \
  -u "<YOUR_SECRET_KEY>:" \
  -H "Stripe-Version: 2026-05-27.preview" \
  -d type=subscription

curl https://api.stripe.com/v1/subscriptions/<SUBSCRIPTION_ID>/resume \
  -u "<YOUR_SECRET_KEY>:" \
  -H "Stripe-Version: 2026-05-27.preview" \
  -d payment_behavior=resume_on_payment_success

curl https://api.stripe.com/v1/subscriptions/<SUBSCRIPTION_ID>/resume \
  -u "<YOUR_SECRET_KEY>:" \
  -H "Stripe-Version: 2026-05-27.preview" \
  -d payment_behavior=resume_on_payment_attempt

WHY THIS HELPS

When implementing subscription lifecycle handling for a subscription using flexible billing mode, pause it to suspend service and invoice generation, then restore service when it resumes.

REQUIREMENTS AND LIMITATIONS

Availability: Public preview
type: Pause type; `subscription` pauses collection, billing, and servicing. Defaults to `subscription`.
payment_behavior: Resume payment behavior; defaults to `resume_on_payment_attempt`. `resume_on_payment_attempt` skips payment during resume; a failed later payment moves the subscription to `past_due`, with no automatic retry. `resume_on_payment_success` attempts payment during resume; on failure the subscription stays paused and Stripe retries failed payments. These are mutually exclusive enum values.
Prerequisite: The subscription must use flexible billing mode to pause.
Prerequisite: The subscription must use `charge_automatically` collection to resume.
Prerequisite: A restricted API key needs `subscription_write` permission to pause or resume subscriptions.
Pausing requires flexible billing mode.

FIRST-PARTY EVIDENCE

Check the installed version and the source before using it. Entry JSON

Report a problem with this card

Tools change faster than your agent’s training data.

Changes

Stripe Subscriptions API adds pause and configurable resume behavior