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 can’t pay for one or more billing cycles.

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 don’t fit your use case, you might want to consider cancelling 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 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.

curl https://api.stripe.com/v1/subscriptions/
{{SUBSCRIPTION_ID}} \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d "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.

curl https://api.stripe.com/v1/subscriptions/
{{SUBSCRIPTION_ID}} \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d "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.

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:

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

curl https://api.stripe.com/v1/subscriptions/
{{SUBSCRIPTION_ID}} \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d "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 behaviour 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:

curl https://api.stripe.com/v1/subscriptions/sub_GTbTiykEwMRog0 \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -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 is not 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.