Stripe: Pause Subscriptions

Stripe always provides a comprehensive package with features for you to use to improve you products and make your clients happier and this is exactly that.

The ability to pause subscription in order to do that you need to do a couple of things:

• The collection method must be Charge Automatically.

• The billing mode must be Flexible.

• API version 2025-06-30.preview or later.

Collection method

By default the Stripe subscriptions are created with this type so you don't need to change anything you can go with it

The Billing Mode

By default the billing method is Basic so in order to use the pause functionality you need to changed to Flexible it can be changed for specific subscription from the dashboard and from the API:

Update it from the Dashboard

To use flexible billing mode, your integration must be on Stripe API version 2025-06-30.basil or later. To see what version you’re on, go to the Workbench overview and look at the API versions section. From there, click Upgrade to upgrade to a newer version.

1. On the Subscriptions page in the Dashboard, select the subscription that you want to migrate.

2. Click Update subscription.

3. Expand the Billing and payment collection section.

4. Set Billing mode to Flexible, and click Update subscription.

Update it using the API

// Don't put any keys in code. See https://docs.stripe.com/keys-best-practices.
// Find your keys at https://dashboard.stripe.com/apikeys.
$stripe = new \Stripe\StripeClient('sk_test_51RRquARcy99RV4czPtcirlPrgNttCr026zIC57B3Y9ZsYW6LWUv0sZv2sOgizGtNGijy6sMFPubOpO1bqTuM2lRg00t5TbV7SG');

$subscription = $stripe->subscriptions->create([
  'items' => [['price' => '{{PRICE_ID}}']],
  'customer' => '{{CUSTOMER_ID}}',
  'billing_mode' => [
    'type' => 'flexible',
    'flexible' => ['proration_discounts' => 'itemized'],
  ],
  'payment_behavior' => 'default_incomplete',
  'payment_settings' => ['save_default_payment_method' => 'on_subscription'],
]);

When creating the subscription you can pass the billing mode and to pass options for the billing mode as in this case proration_discounts .

There are cases when the subscription can't be paused, different cases and what to reach the goal:

Resume Subscription

In order to resume the subscription it should use the charge_automatically collection type.

Dashboard

To resume a paused subscription in the Dashboard:

1. On the Subscriptions page, find the paused subscription, click the overflow menu (), and select Resume subscription.

2. Configure proration and billing cycle anchor settings.

3. Click Resume subscription.

API

// Don't put any keys in code. See https://docs.stripe.com/keys-best-practices.
// Find your keys at https://dashboard.stripe.com/apikeys.
// This example uses the public preview SDK. See https://github.com/stripe/stripe-php#public-preview-sdks
$stripe = new \Stripe\StripeClient('sk_test_51RRquARcy99RV4czPtcirlPrgNttCr026zIC57B3Y9ZsYW6LWUv0sZv2sOgizGtNGijy6sMFPubOpO1bqTuM2lRg00t5TbV7SG');

$subscription = $stripe->subscriptions->resume(
  'sub_1234567890',
  [
    'payment_behavior' => 'resume_on_payment_success',
    'billing_cycle_anchor' => 'now',
    'proration_behavior' => 'create_prorations',
  ]
);

For the subscriptions resume events are sent(as with every for resource in Stripe) which are:

example payload of such event will look something like this:

{
  "id": "evt_1SrpXjRnJ89Z4rKkFxe9waAz",
  "object": "event",
  ...
  "data": {
    "object": {
      "id": "sub_1SrpWtRnJ89Z4rKknfSwXkBc",
      "object": "subscription",
      ...
      "latest_invoice": "in_1SrpWtRnJ89Z4rKkzYBCF1MY",
      ...
      "status": "paused",
      ...
    }
  },
  ...
  "type": "customer.subscription.paused"
}

Testing

For the testing you can use sandbox environment with Stripe Test Clock to "speed" up the process and to have the ability to "move" back and forth in time to test the behavior of the subscriptions.

Conclusion

Subscription pausing is a great away of give your users a "cushion" especially if your product is used to help start some type of payed action. The functionality is well documented and everything that you need it's right there if there is something that you are not sure about the stripe support is right there at your disposals always ready to help you to solve your problems.