# Pause payment collection

Learn how to pause payment collection on subscriptions.

Subscriptions with `paused collection` can’t move into `status=paused`. Only [ending free trial periods without a payment method](https://docs.stripe.com/billing/subscriptions/trials.md#create-free-trials-without-payment) cause subscriptions to enter a [paused `status`](https://docs.stripe.com/billing/subscriptions/overview.md#subscription-statuses).

Pausing payment collection is often used to temporarily offer your services for free. This is sometimes referred to as a “grace period” if a customer needs additional time to pay or can’t pay for one or more billing cycles.

You can pause or resume collection in the [Stripe Dashboard](https://support.stripe.com/questions/how-to-pause-or-cancel-subscriptions) or the API. While collection is paused, *subscriptions* still generate *invoices*, but you have a few options for handling these invoices.  Review the following use cases to determine the best approach for you:

| Use case                                                                                        | API configuration                 |
| ----------------------------------------------------------------------------------------------- | --------------------------------- |
| [Temporarily offer services for free and never collect payment](#collect-payment-never)         | Use `behavior=void`               |
| [Temporarily offer services for free and collect payment later](#collect-payment-later)         | Use `behavior=keep_as_draft`      |
| [Temporarily offer services for free and mark invoice as uncollectible](#mark-as-uncollectible) | Use `behavior=mark_uncollectible` |

If these options don’t fit your use case, you might want to consider [canceling subscriptions](https://docs.stripe.com/billing/subscriptions/cancel.md) instead.

Invoices created before subscriptions are paused continue to be [retried](https://docs.stripe.com/invoicing/automatic-collection.md) unless you [void](https://docs.stripe.com/api/invoices/void.md) them.

## Temporarily offer services for free and never collect payment 

If you temporarily want to offer your services for free and you don’t want to collect payment on the invoice (for example, a “grace period”), you can void invoices that your subscription creates to make sure that your customers aren’t charged and the subscription remains `status=active`. Use the Subscription ID to update `pause_collection[behavior]` to `void` and `pause_collection[resumes_at]` to the date you want to start collecting payments again.

```dotnet
StripeConfiguration.ApiKey = "<<secret key>>";

var options = new SubscriptionUpdateOptions
{
    PauseCollection = new SubscriptionPauseCollectionOptions { Behavior = "void" },
};
var service = new SubscriptionService();
Subscription subscription = service.Update("<<subscription>>", options);
```

```go
stripe.Key = "<<secret key>>"

params := &stripe.SubscriptionParams{
  PauseCollection: &stripe.SubscriptionPauseCollectionParams{
    Behavior: stripe.String(string(stripe.SubscriptionPauseCollectionBehaviorVoid)),
  },
};
result, err := subscription.Update("<<subscription>>", params);
```

```java
Stripe.apiKey = "<<secret key>>";

Subscription resource = Subscription.retrieve("<<subscription>>");

SubscriptionUpdateParams params =
  SubscriptionUpdateParams.builder()
    .setPauseCollection(
      SubscriptionUpdateParams.PauseCollection.builder()
        .setBehavior(SubscriptionUpdateParams.PauseCollection.Behavior.VOID)
        .build()
    )
    .build();

Subscription subscription = resource.update(params);
```

```node
const stripe = require('stripe')('<<secret key>>');

const subscription = await stripe.subscriptions.update(
  '<<subscription>>',
  {
    pause_collection: {
      behavior: 'void',
    },
  }
);
```

```python
import stripe
stripe.api_key = "<<secret key>>"

subscription = stripe.Subscription.modify(
  "<<subscription>>",
  pause_collection={"behavior": "void"},
)
```

```php
$stripe = new \Stripe\StripeClient('<<secret key>>');

$subscription = $stripe->subscriptions->update(
  '<<subscription>>',
  ['pause_collection' => ['behavior' => 'void']]
);
```

```ruby
Stripe.api_key = '<<secret key>>'

subscription = Stripe::Subscription.update(
  '<<subscription>>',
  {pause_collection: {behavior: 'void'}},
)
```

All invoices created before the `resumes_at` date are immediately marked as void. Stripe won’t send any upcoming invoice emails or webhooks and the subscription’s status remains unchanged.

If you don’t set a `resumes_at` date, the subscription remains paused until you unset `pause_collection`.

## Temporarily offer services for free and collect payment later 

If you want to temporarily offer your services for free and collect payments later, set `pause_collection[behavior]=keep_as_draft`. If you know when you want to resume collection, pass a timestamp for `resumes_at`.

```dotnet
StripeConfiguration.ApiKey = "<<secret key>>";

var options = new SubscriptionUpdateOptions
{
    PauseCollection = new SubscriptionPauseCollectionOptions { Behavior = "keep_as_draft" },
};
var service = new SubscriptionService();
Subscription subscription = service.Update("<<subscription>>", options);
```

```go
stripe.Key = "<<secret key>>"

params := &stripe.SubscriptionParams{
  PauseCollection: &stripe.SubscriptionPauseCollectionParams{
    Behavior: stripe.String(string(stripe.SubscriptionPauseCollectionBehaviorKeepAsDraft)),
  },
};
result, err := subscription.Update("<<subscription>>", params);
```

```java
Stripe.apiKey = "<<secret key>>";

Subscription resource = Subscription.retrieve("<<subscription>>");

SubscriptionUpdateParams params =
  SubscriptionUpdateParams.builder()
    .setPauseCollection(
      SubscriptionUpdateParams.PauseCollection.builder()
        .setBehavior(SubscriptionUpdateParams.PauseCollection.Behavior.KEEP_AS_DRAFT)
        .build()
    )
    .build();

Subscription subscription = resource.update(params);
```

```node
const stripe = require('stripe')('<<secret key>>');

const subscription = await stripe.subscriptions.update(
  '<<subscription>>',
  {
    pause_collection: {
      behavior: 'keep_as_draft',
    },
  }
);
```

```python
import stripe
stripe.api_key = "<<secret key>>"

subscription = stripe.Subscription.modify(
  "<<subscription>>",
  pause_collection={"behavior": "keep_as_draft"},
)
```

```php
$stripe = new \Stripe\StripeClient('<<secret key>>');

$subscription = $stripe->subscriptions->update(
  '<<subscription>>',
  ['pause_collection' => ['behavior' => 'keep_as_draft']]
);
```

```ruby
Stripe.api_key = '<<secret key>>'

subscription = Stripe::Subscription.update(
  '<<subscription>>',
  {pause_collection: {behavior: 'keep_as_draft'}},
)
```

All invoices created before the `resumes_at` date remain in `draft` state and `auto_advance` is set to `false`. During this time, Stripe won’t send any upcoming invoice emails or webhooks for these invoices and the subscription’s status remains unchanged.

If you don’t set a `resumes_at` date, the subscription remains paused until you unset `pause_collection`.

If you have custom logic that finalizes invoices you might need to disable or modify it so that it doesn’t conflict with these settings.

When you’re ready to collect payment for these invoices, set `auto_advance` back to `true`. If you don’t have the invoice IDs, you can use Subscription IDs to check for invoices with `status=draft`. Using the invoice ID, you can then update `auto_advance=true`:

```dotnet
StripeConfiguration.ApiKey = "<<secret key>>";

var options = new InvoiceUpdateOptions { AutoAdvance = true };
var service = new InvoiceService();
Invoice invoice = service.Update("<<invoice>>", options);
```

```go
stripe.Key = "<<secret key>>"

params := &stripe.InvoiceParams{AutoAdvance: stripe.Bool(true)};
result, err := invoice.Update("<<invoice>>", params);
```

```java
Stripe.apiKey = "<<secret key>>";

Invoice resource = Invoice.retrieve("<<invoice>>");

InvoiceUpdateParams params = InvoiceUpdateParams.builder().setAutoAdvance(true).build();

Invoice invoice = resource.update(params);
```

```node
const stripe = require('stripe')('<<secret key>>');

const invoice = await stripe.invoices.update(
  '<<invoice>>',
  {
    auto_advance: true,
  }
);
```

```python
import stripe
stripe.api_key = "<<secret key>>"

invoice = stripe.Invoice.modify(
  "<<invoice>>",
  auto_advance=True,
)
```

```php
$stripe = new \Stripe\StripeClient('<<secret key>>');

$invoice = $stripe->invoices->update('<<invoice>>', ['auto_advance' => true]);
```

```ruby
Stripe.api_key = '<<secret key>>'

invoice = Stripe::Invoice.update('<<invoice>>', {auto_advance: true})
```

## Temporarily offer services for free and mark invoices as uncollectible 

If you temporarily want to offer your services for free and mark any invoices generated by the subscription as uncollectible, use the Subscription ID to update `pause_collection[behavior]` to `mark_uncollectible` and optionally `pause_collection[resumes_at]` to the date you want to start collecting payments again. This makes sure that any downstream reporting is accurate, your customer isn’t charged, and the subscription remains `status=active`.

```dotnet
StripeConfiguration.ApiKey = "<<secret key>>";

var options = new SubscriptionUpdateOptions
{
    PauseCollection = new SubscriptionPauseCollectionOptions { Behavior = "mark_uncollectible" },
};
var service = new SubscriptionService();
Subscription subscription = service.Update("<<subscription>>", options);
```

```go
stripe.Key = "<<secret key>>"

params := &stripe.SubscriptionParams{
  PauseCollection: &stripe.SubscriptionPauseCollectionParams{
    Behavior: stripe.String(string(stripe.SubscriptionPauseCollectionBehaviorMarkUncollectible)),
  },
};
result, err := subscription.Update("<<subscription>>", params);
```

```java
Stripe.apiKey = "<<secret key>>";

Subscription resource = Subscription.retrieve("<<subscription>>");

SubscriptionUpdateParams params =
  SubscriptionUpdateParams.builder()
    .setPauseCollection(
      SubscriptionUpdateParams.PauseCollection.builder()
        .setBehavior(SubscriptionUpdateParams.PauseCollection.Behavior.MARK_UNCOLLECTIBLE)
        .build()
    )
    .build();

Subscription subscription = resource.update(params);
```

```node
const stripe = require('stripe')('<<secret key>>');

const subscription = await stripe.subscriptions.update(
  '<<subscription>>',
  {
    pause_collection: {
      behavior: 'mark_uncollectible',
    },
  }
);
```

```python
import stripe
stripe.api_key = "<<secret key>>"

subscription = stripe.Subscription.modify(
  "<<subscription>>",
  pause_collection={"behavior": "mark_uncollectible"},
)
```

```php
$stripe = new \Stripe\StripeClient('<<secret key>>');

$subscription = $stripe->subscriptions->update(
  '<<subscription>>',
  ['pause_collection' => ['behavior' => 'mark_uncollectible']]
);
```

```ruby
Stripe.api_key = '<<secret key>>'

subscription = Stripe::Subscription.update(
  '<<subscription>>',
  {pause_collection: {behavior: 'mark_uncollectible'}},
)
```

If you set `pause_collection[behavior]` to `mark_uncollectible`, we’ll stop active payment collection on new invoices the subscription creates before the `resumes_at` date.
Stripe won’t send any upcoming invoice emails or webhooks for these invoices.

Despite this pause, Stripe applies any existing customer balance to invoices. This behavior helps use available funds before we mark an invoice as `uncollectible`.
If the invoice’s `total` is paid off entirely using customer balance, then the invoice’s status is set to `paid`.
Otherwise, the invoice’s status is set to `uncollectible`.

If you don’t set a `resumes_at` date, the payment collection on the subscription remains paused until you unset `pause_collection`.

## Manually unpausing 

To resume collecting payments at any time, you can update the subscription and unset `pause_collection`:

```bash
curl https://api.stripe.com/v1/subscriptions/sub_GTbTiykEwMRog0 \
  -u <<secret key>>: \
  -d "pause_collection"=" "
```

```ruby
<<setup key>>

Stripe::Subscription.update(
  'sub_GTbTiykEwMRog0',
  {
    pause_collection: ''
  }
)
```

```python
<<setup key>>

stripe.Subscription.modify(
  'sub_GTbTiykEwMRog0',
  pause_collection='',
)
```

```php
<<setup key>>

\Stripe\Subscription::update(
  'sub_GTbTiykEwMRog0',
  [
    'pause_collection' => '',
  ]
);
```

```java
<<setup key>>

Subscription subscription =
  Subscription.retrieve("sub_GTbTiykEwMRog0");
SubscriptionUpdateParams params =
  SubscriptionUpdateParams.builder()
    .setPauseCollection(EmptyParam.EMPTY)
    .build();
subscription = subscription.update(params);
```

```javascript
<<setup key>>

const subscription = await stripe.subscriptions.update(
  'sub_GTbTiykEwMRog0',
  {
    pause_collection: '',
  }
);
```

```go
<<setup key>>

params := &stripe.SubscriptionParams{}
params.AddExtra("pause_collection", "")
s, _ := subscription.Update("sub_GTbTiykEwMRog0", params)
```

```dotnet
<<setup key>>

var options = new SubscriptionUpdateOptions();
options.AddExtraParam("pause_collection", "");
var service = new SubscriptionService();
service.Update("sub_GTbTiykEwMRog0", options);
```

Resuming collection this way only affects future invoices.

## Pausing and subscription schedules 

If you pause a subscription on a [subscription schedule](https://docs.stripe.com/billing/subscriptions/subscription-schedules.md), the scheduled updates still take effect. However, payment is not collected while the subscription is paused. When you want to collect payment again, you need to [manually unpause](#unpausing) the subscription. You also need to update `auto_advance` to `true` on any invoices with `status=draft` that you want to collect payment on.