Pause payment collection

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 cant pay for one or more billing periods.

Pause subscription versus pause payment collection

Pausing payment collection keeps the subscription active, invoices still generate, and only collection pauses. Your customers keep access to the service while you pause collection.

Pausing a subscription is different, because it stops both service and billing. The subscription moves to paused status, Stripe stops generating invoices, and your customer loses access to the subscriptions service for the duration of the pause.

You can pause or resume collection in the Stripe Dashboard 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:

If these options dont fit your use case, you might want to consider canceling subscriptions instead.

Invoices created before subscriptions are paused continue to be retried unless you void them.

Temporarily offer services for free and never collect payment

If you temporarily want to offer your services for free and you dont 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 arent 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.

curl https://api.stripe.com/v1/subscriptions/
{{SUBSCRIPTION_ID}} \
  -u "sk_test_wU7nrJCZspk1NPDxiQgAF05q:" \
  -d "pause_collection[behavior]=void"

All invoices created before the resumes_at date are immediately marked as void. Stripe wont send any upcoming invoice emails or webhooks and the subscriptions status remains unchanged.

If you dont 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.

curl https://api.stripe.com/v1/subscriptions/
{{SUBSCRIPTION_ID}} \
  -u "sk_test_wU7nrJCZspk1NPDxiQgAF05q:" \
  -d "pause_collection[behavior]=keep_as_draft"

All invoices created before the resumes_at date remain in draft status and auto_advance is set to false. During this time, Stripe wont send any upcoming invoice emails or webhooks for these invoices and the subscriptions status remains unchanged.

If you dont set a resumes_at date, the subscription remains paused until you unset pause_collection.

When you want to collect payment for these invoices:

1. Unset pause_collection on the subscription. While paused, Stripe automatically sets auto_advance=false on all draft invoices, even if you explicitly set it to true. To unset pause_collection, see Manually unpausing.
2. Set auto_advance=true on each draft invoice. If you dont have the invoice IDs, look them up using the subscription ID with status=draft as a filter. For example:

curl https://api.stripe.com/v1/invoices/
{{INVOICE_ID}} \
  -u "sk_test_wU7nrJCZspk1NPDxiQgAF05q:" \
  -d 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 isnt charged, and the subscription remains status=active.

curl https://api.stripe.com/v1/subscriptions/
{{SUBSCRIPTION_ID}} \
  -u "sk_test_wU7nrJCZspk1NPDxiQgAF05q:" \
  -d "pause_collection[behavior]=mark_uncollectible"

If you set pause_collection[behavior] to mark_uncollectible, well stop active payment collection on new invoices the subscription creates before the resumes_at date. Stripe wont 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 invoices total is paid off entirely using customer balance, then the invoices status is set to paid. Otherwise, the invoices status is set to uncollectible.

If you dont 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:

curl https://api.stripe.com/v1/subscriptions/sub_GTbTiykEwMRog0 \
  -u sk_test_wU7nrJCZspk1NPDxiQgAF05q: \
  -d "pause_collection"=

Resuming collection this way only affects future invoices.

Pausing and subscription schedules

If you pause a subscription on a subscription schedule, the scheduled updates still take effect. However, payment isnt collected while the subscription is paused. When you want to collect payment again, you need to manually unpause the subscription. You also need to update auto_advance to true on any invoices with status=draft that you want to collect payment on.