Pause payment collection
Pausing payment collection is often used to temporarily offer your services for free or to stop payments if you can’t provide your services. While collection is paused, subscriptions still generate invoices but you have a few options for handling these invoices.
You can pause or resume collection in the Stripe Dashboard or the API. To use the API, review the following use cases to determine the best approach for you.
Pausing collection can affect accounting data, such as monthly recurring revenue (MRR).
Use case | API configuration |
|---|---|
| Offer services for free | Use behavior=mark_uncollectible |
| Temporarily offer services for free and collect payment later | Use behavior=keep_as_draft |
| Unable to provide services | Use behavior=void |
If these options don’t 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.
Offer services for free
If you want to offer your services for free, update the subscription’s pause_collection[behavior] to mark_uncollectible. If you know when you want to resume collection, pass a timestamp for resumes_at as well.
All invoices generated before the resumes_at date are immediately marked as uncollectible. 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.
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 as well.
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:
Unable to provide services
If you can’t provide your services for a certain period of time, you can void invoices that are created by your subscriptions so that your customers aren’t charged. 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.
All invoices created before the resumes_at date are immediately voided. 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.
Manually unpausing
To resume collecting payments at any time, you can update the subscription and unset 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.