Say you sell a small tool to wedding photographers. You have 40-something paying customers, mostly monthly. In November one of them writes:
"Season's done for me. Can I pause until March instead of cancelling? I don't want to lose my setup."
That's a good email to get. They're not leaving, they just don't want to pay for four months of nothing. But if you've never done a pause before, you open the Stripe Dashboard and find there are now two different buttons with "pause" in the name, and they do very different things. Pick the wrong one and you either keep charging them (well, invoicing them) all winter, or you lock someone out who only wanted a payment break.
This post is the version I'd want before answering that email. What each pause actually does in Stripe, what your app has to check, and a small pause policy you can write once and reuse. With under 50 customers every pause is a person you'll talk to again in March, so it's worth getting right.
Stripe has two kinds of pause now
This changed recently, so older blog posts are out of date. For years the only "pause" was pause_collection. On 2026-09-30 Stripe's changelog added the ability to pause and resume subscriptions on demand (it was in preview earlier this year). So now:
1. Pause payment collection (pause_collection on the subscription)
- The subscription stays
active. - Invoices still get created every period, Stripe just doesn't collect them.
- The customer keeps access, because nothing about the status changed.
- Stripe's own docs describe it as a grace period, for when "a customer needs more time to pay or can't pay for one or more billing periods."
2. Pause the subscription (the newer pause endpoint, or "Pause subscription" in the Dashboard)
- The status changes to
paused. - Stripe stops generating invoices until you resume.
- It's meant to stop service too. The docs literally say to make clear that pausing "stops both service delivery and invoice generation."
- It needs the subscription to be on flexible billing mode, and a few other things (more on that below).
So the photographer who's away until March wants #2. A customer who says "money is tight this month, can I keep using it and pay later" wants #1. Most of the confusion is just using one for the other.
The easy one: pausing payment collection
You can do this from the Dashboard (open the subscription, the ⋯ menu, Pause payment collection) or with one API call:
curl https://api.stripe.com/v1/subscriptions/sub_123 \
-u "sk_live_...:" \
-d "pause_collection[behavior]=mark_uncollectible" \
-d "pause_collection[resumes_at]=1803859200" # 2027-03-01 00:00 UTC
resumes_at is optional. Leave it out and collection stays paused until you unset it yourself, which is how you end up with a customer who quietly used the product free for a year because nobody remembered.
The part people skip is behavior. It decides what happens to the invoices Stripe keeps creating while collection is paused:
| behavior | what happens to each invoice | use it when |
|---|---|---|
keep_as_draft |
stays a draft, auto_advance off |
you're deferring, they'll pay later |
mark_uncollectible |
marked uncollectible (customer balance applied first) | you're forgiving the period |
void |
voided, no record of a charge | you're forgiving and want no trail |
Two things in the docs that are easy to miss:
-
keep_as_draftmeans they still owe you. When you resume, the drafts don't collect themselves. You have to turn on automatic collection for each one (auto_advance=true), and then they get charged for the paused months too. If you told the customer "no charge while paused", don't pick this one. - Invoices from before the pause keep getting retried unless you void them. So if the customer already had a failed renewal and you pause collection to be nice, Stripe can still retry that old invoice. Look at their open invoices before you click.
Also, while collection is paused Stripe doesn't send upcoming invoice emails or webhooks for those invoices. Quiet is nice, but it also means your own "your plan renews soon" logic, if it hangs off those webhooks, goes silent for that customer.
The real pause: status becomes paused
In the Dashboard it's the ⋯ menu, Pause subscription. You choose whether it starts now or on a date, and whether it stays paused "until you resume it" or until a specific date. The date option is the one you want for the photographer: pause now, resume March 1.
What happens when you pause, per Stripe's docs:
- status changes to
paused -
current_period_endgets moved to the moment you paused - no new invoices until resume
- you get
customer.subscription.paused(pluscustomer.subscription.updated)
And the money part. By default Stripe credits the unused time, from the pause moment to the end of the period, as a pending invoice item. Stripe's example: $30/month plan, paused on day 15, you get a -$15 pending item. Resume on day 45 and the resumption invoice has the -$15 credit plus a fresh $30 period, so they pay $15 and a new cycle starts. You can change that with bill_for[unused_time_from] (now, item_current_period_start, or none), and invoicing_behavior decides if the credit sits as a pending item (default) or gets invoiced right away.
If you'd rather see the numbers before you commit, Stripe lets you preview a pause invoice, but only if invoicing_behavior is invoice. With the default it returns a 404, which is easy to read as "something's broken", so heads up.
Why the pause button might be greyed out
Stripe lists the cases where you can't pause:
- the subscription uses
send_invoiceinstead of charging automatically - it's on classic billing mode (you'd migrate it to flexible first)
- it's in a free trial set with
trial_end/trial_period_days - status is
unpaid,incomplete,incomplete_expiredorcanceled - it has a subscription schedule attached (you pause through the schedule instead)
On billing mode: per Stripe's docs, API version 2025-09-30.clover and later default new subscriptions to flexible, older versions default to classic, and Dashboard-created ones follow a setting under Settings > Billing > Subscriptions and emails. If you set things up a while ago there's a fair chance your early subscribers are classic. Migration is one way only (flexible can't go back to classic), so read Stripe's compare page before migrating everyone just to get a pause button. For one customer who wants a pause next week, pause_collection plus a note might honestly be fine.
Resuming without a surprise
The resume step has a default that I'd change. The payment_behavior options:
-
resume_on_payment_attempt(default): the resume call doesn't try to charge. If the charge on that invoice fails later, the subscription goes topast_dueand Stripe doesn't retry. -
resume_on_payment_success(Stripe calls it recommended): it tries the payment in the request, stayspauseduntil payment works, and retries.
Also, a resume request can return 200 while the subscription is still paused and the invoice is waiting to be paid. So don't flip access back on just because the API call didn't throw. Check the returned status, or wait for customer.subscription.resumed.
One small trap: if the customer has a coupon, it keeps counting down during the pause. A three month launch discount paused for three months is just gone when they come back. If you promised it, you'll need to fix that by hand.
What your app checks
This is where most of the bugs are. Stripe recommends using the subscription status to start and stop service. So:
- Collection paused → status is still
active→ your paywall lets them in. That's what you want for a grace period. - Subscription paused → status is
paused→ your paywall should let them read their stuff but not use the paid features. Your call, but decide it before the first pause, not during.
The other catch: paused isn't only from a pause request. A trial that ends without a card can also put a subscription in paused. If your app shows "Add a card to continue your trial" for every paused, your photographer gets told their trial ended. Stripe gives you status_details.paused.subscription.type to tell them apart: pause_requested, trial_end_without_payment_method, system, and with the auto pause after payment failures added in the same release, first_payment_failure and final_payment_failure.
Rough version of the access check:
function access(sub: Stripe.Subscription) {
if (sub.status === "active" || sub.status === "trialing") {
return sub.pause_collection ? "full_grace" : "full";
}
if (sub.status === "paused") {
const why = sub.status_details?.paused?.subscription?.type;
if (why === "trial_end_without_payment_method") return "add_card";
if (why === "first_payment_failure" || why === "final_payment_failure") return "fix_payment";
return "paused_readonly"; // pause_requested, system
}
return "none"; // past_due etc. handled the way you already do
}
(Check the field names against your SDK version, status_details came with the newer API versions.) I went through what every status should mean for access in how Stripe's subscription statuses map to access, and paused was the one most paywalls forget.
The customer can't do this themselves (yet)
In Stripe's Customer Portal configuration docs there are toggles for switching plans, quantities, cancelling, cancellation reasons and retention coupons. I didn't find a pause option. So under 50 customers, a pause usually starts as an email to you, and that's fine. A support email at this size is a conversation, and it's often the only time a quiet customer tells you how they use the thing.
If you do want pause as self serve, put it in your own cancel flow. Offer it only when the reason fits (seasonal, project ended, taking a break) and never as a wall in front of the cancel button. I wrote more about a cancel flow that offers pause without dark patterns, and the short version is: pause is for "not right now", cancel is for "not for me", and mixing them makes people angry later.
A pause policy you can write in ten minutes
Write this down once, in a note, before the second pause request:
-
Which pause. "Away / not using it" gets a real pause. "Can't pay right now but still using it" gets paused collection, with
mark_uncollectibleif you're forgiving andkeep_as_draftonly if you said they'd pay later. - Max length. Something like up to 3 months, with a resume date always set. "Until you resume it" is how pauses turn into forgotten accounts.
- What they see while paused. Read-only, export still works, nothing deleted. Say this in the reply.
- What the first invoice after looks like. If you keep the default credit, tell them the first charge in March will be smaller than usual, or they'll think it's a mistake.
- Coupons. Mention it if a discount will run out during the pause.
- Reminder. Put a calendar reminder a few days before the resume date and send a short "you're back on March 1, here's what you'll be charged" email. I didn't see anything in the pause docs about Stripe emailing the customer before a resume, so I'd send this one yourself.
The reply to the photographer then writes itself:
"Sure, I've paused your subscription from today until March 1. You won't be charged before then and your projects stay as they are, you can still log in and look at them. Your first charge in March will be a bit lower because of the unused days from this month. I'll email you a few days before."
That's it. No retention trick, no form.
Quick checklist
- [ ] Know which pause you're using:
pause_collection(stays active, invoices still created) or real pause (paused, no invoices) - [ ] For
pause_collection, pickbehavioron purpose, and setresumes_at - [ ] Look at open invoices before pausing, old ones keep retrying
- [ ] For real pause: flexible billing mode,
charge_automatically, no trial, no schedule - [ ] Resume with
resume_on_payment_success, confirmstatusbefore giving access back - [ ] Paywall handles
pausedand readsstatus_detailsso a paused customer doesn't see trial copy - [ ] Coupons keep running during a pause
- [ ] Reminder email before resume
Stripe's pause subscriptions docs are the source of truth for the fields above, and the pages changed recently, so check them before you build anything. And since the same release also lets Stripe pause a subscription automatically after a failed payment, it's worth deciding how that fits with your retry emails. I put together a longer playbook on recovering failed payments before they turn into churn if you're setting that up anyway.
So, a question for anyone already doing this: when a customer asks to pause, do you use pause_collection, the newer pause, or do you just cancel and re-subscribe them later? And if it's pause_collection, which behavior did you go with?
Top comments (33)
the behavior field is the part that bites people. pause collection with mark_uncollectible is fine for a real grace period, but the invoices-from-before-the-pause detail is the one that surprises: a failed renewal you paused to be nice about can still get retried, so the customer comes back in March and finds months of debt sitting there. worth putting the resumes_at date in the pause email too, so March is a promise on both sides rather than a queue you have to remember to clear.
agreed, the old failed renewal still retrying is the nasty one, you pause to be nice and they come back to a pile of debt. putting the resumes_at date in the pause email is a good call too, then march is written down on both sides and not just in my head.
the retry pile is the trap because it looks like diligence in the dashboards. billing retries the invoice, dunning fires, the customer already thinks they're paused, and support inherits the confusion a month later. i've started treating pause as a state machine rather than a boolean: paused flag on the customer, existing invoices frozen or explicitly written off, and the resume date stamped in the confirmation email so nobody has to remember it.
state machine instead of a boolean makes sense, mostly because of the "frozen or written off" step. a paused flag with old invoices still live is how dunning ends up emailing someone who thinks they're on a break. deciding what happens to each open invoice at the moment of the pause is the bit i'd skip if i didn't write it down.
the moment-of-pause decision is the one that shows up in month-end disputes later. what kept us honest was forcing each open invoice to either finish its cycle or be zeroed out, nothing in between. a half-paused invoice is the worst of both worlds: no revenue recognized, dunning still running, and nobody can say what the customer actually owes.
"finish its cycle or be zeroed out, nothing in between" is a clean rule. the half-paused invoice is exactly the one where support, billing and the customer all have a different answer to "what do i owe". at small scale i'd probably just void anything open at the moment of the pause and note it on the customer, simpler than tracking partial states.
voiding at the moment of pause holds until the first customer with usage already racked up that cycle pushes back, and then support is doing refunds by hand. the middle ground i've seen stick is void-and-credit: zero it out, but leave the note where both the customer and the ledger can see it, so "what do i owe" never depends on who you ask. and agreed on the under-50 point, tracking partial pause states is a whole subsystem nobody at that size should be maintaining.
voiding open invoices at pause is the honest default, agreed. the one wrinkle worth planning for is usage-billed lines: if the customer used the product for part of the cycle, a zeroed-out invoice makes the next month's charge quietly disagree with what they actually consumed, and that gap is where the support thread starts. a one-line note on the customer record naming what was voided and why is usually enough to prevent it.
The usage-billed line is a good wrinkle, I only thought about flat-price plans. When a customer pauses mid-cycle, would you bill the used part right then, or let it roll into the first invoice after they resume?
immediate proration on pause is the cleaner answer for usage-billed: the usage meter already has timestamps, so an invoice line cut at the pause moment with a distinct period makes reconciliation trivial and avoids a resume invoice that spans two billing periods. rolling it forward reads better to the customer though, so the defensible middle is bill-on-pause with a credit memo if they never resume.
bill-on-pause with a credit memo if they never resume is a nice middle. a line with its own period also means "what do i owe" can be answered from the invoice alone, without anyone digging through the usage meter. i'd still put the used amount in the pause confirmation email so the charge isn't a surprise when it shows up.
the confirmation-email point is underrated: a pause charge that surprises the customer costs a support ticket and sometimes a chargeback, so the used-amount line in the pause email is doing retention work, not just billing hygiene. the self-service path changes it too, when customers can pause without talking to anyone the invoice has to explain itself entirely on its own, since nobody promised them anything on a call. the credit memo timing is worth pinning down as well, issuing it at pause rather than at the period close keeps the ledger readable even if the account never comes back.
agree on the pause confirmation email. it also gives you a place to state the resume terms in writing, which at under 50 customers matters more than any policy page since the founder is the policy page. one practical addition: log the pause request timestamp against the subscription row the same way you would a cancellation, so if the customer later disputes what was paused and when, the invoice history settles it without anyone scrolling back through chat.
logging the pause request timestamp on the subscription row like a cancellation makes sense, it's the same "what happened and when" question later. and agreed on the resume terms, at this size the confirmation email pretty much is the policy page.
the timestamp is the piece that survives staff changes too: six months later whoever inherits the "why were we billed while paused" ticket wasn't there when the pause happened, and a logged request time plus the terms that were emailed turns that conversation from archaeology into a lookup. cheap to store, expensive to reconstruct.
cheap to store, expensive to reconstruct is basically the argument for logging anything billing related. and at under 50 customers the person who inherits that ticket is usually the founder six months later who forgot the whole thing, so it's the same problem, just with one person
the founder-six-months-later case is the one that settles it. re-deriving why a charge happened from git history and scattered slack threads is a bad afternoon, and a pause_reason plus pause timestamp on the subscription row costs nothing to keep around.
yeah, pause_reason is one of those columns nobody adds until they've needed it once. would you keep it free text or a short fixed list? at this size i'd lean free text, the reasons are all different anyway and there aren't enough of them to chart
free text at this size, agreed. the one guardrail worth keeping is nudging people to write a sentence, not a code: "can't pay until january, card was reissued" tells you more at renewal time than "other" ever will. a fixed list only earns its keep once someone's asked for a chart, and under 50 customers you'd be inventing categories from a sample of one.
sentence over code is a good rule. i'd probably put a one-line placeholder in the form so people don't leave it blank. when you've looked back at those notes at renewal, did the free-text ones actually change what you offered, or mostly just explain the pause?
mostly they explain the pause, honestly, but the ones that change the offer are the ones that name a date. "card was reissued" means you can reach out with the new-card link before renewal instead of discovering the lapse after, and "waiting on funding" means aligning the next charge to their timeline instead of renewing into a dead account. the placeholder is the underrated half of it, though: "what happened, and when do you expect to be back?" written into the box does more than any validation rule, it makes the sentence-shaped answer the path of least resistance.
Naming a date is a good signal, a reason alone doesn't tell you when to reach out. Do you set a reminder on the subscription itself for that date, or is it more of a manual check at renewal?
a bit of both. the date the customer names goes on the subscription itself as the resume date, so billing picks it up automatically, but the outreach half is manual: we check the paused list when that date arrives, because "check back on the 1st" is a much warmer window than anything a dunning cycle would time. so the reminder is for the team, the resume date is for the billing system, and mixing those up is how a pause turns into a silent churn.
That split between the billing date and the human check is the useful part. A resume date can handle the automatic piece, while the reminder keeps the conversation from going quiet. Do you also record what the customer expects when that date comes?
yes, and it lives in the same record as the pause itself: what they expect the product to be doing on the other side, and what 'working again' means for them. it is one field, and it turns the reactivation touch from a discovery call into a check-in. teams that skip it usually end up re-onboarding from zero, and the customer feels the difference.
"Every pause is a person you'll talk to again in March" is the sentence the Stripe dashboard cannot help with. The pause itself is a settings decision; the March conversation is a follow-up, and follow-ups at 40 customers live in the founder's memory. Write the pause policy once, and in the same sitting write the resume rule: who notices on the first of March that a paused customer has not come back, and what they say. The win is not pausing cleanly, it is being the one tool that remembered to check in before the customer had to.
yeah, the pause is one api call, the march part is the one that actually gets forgotten. writing the resume rule in the same sitting is a good way to put it, otherwise the "who checks on the first" question just never gets an owner. even a calendar entry with their name and the date beats trusting memory at 40 customers.
A calendar entry beats memory because it survives the founder getting busy, which is exactly when the March check would be dropped. The one upgrade worth adding: the entry names what "came back" means before the date arrives. If the customer logs in twice in the last week of February, nobody needs to call. If they do not, the entry says who writes and what the first line is. Deciding that in advance is what turns a reminder into a process.
deciding what "came back" means before the date is a good upgrade. otherwise the march entry just turns into "check on them" and you end up guessing on the day. two logins in the last week of february is a nice concrete bar, and if they haven't come back by then, the reminder already says who writes and what to say.
Exactly, "check on them" is a wish, not a process, because it leaves three decisions for the worst day: what counts as back, who notices, and what the first line says. The February logins bar handles the first. One more worth deciding in the same sitting: what happens after the nudge gets no reply in a week, whether the pause converts to a cancel conversation or stays open. Written down once, the whole pause lifecycle runs without anyone improvising in March.
yeah the no-reply case is the one i'd leave open by accident. i think i'd make it a cancel conversation after a week, not an automatic cancel, because some people just miss the email. but the pause shouldn't quietly stay open forever either, that's how you end up with "paused" customers from a year ago that nobody remembers pausing.
The zombie pause is the argument for writing the end condition at the start, not just the check-in date. "Cancel conversation after a week" is the right shape: a person decides, nobody auto-cancels on a missed email. The entry just needs to say what the conversation is and who opens it, otherwise the week passes and the pause quietly rolls into month two. Paused a year ago and nobody remembers is what a state with no end condition looks like from the inside.
"what the conversation is and who opens it" is the bit i'd skip without noticing. under 50 customers the who is basically always the founder, so the real gap is the what. i'd probably write the first line of that email straight into the calendar entry, so on the day it's just send it, not sit there figuring out what to say.