How to pause subscriptions on Paddle Billing

Some customers do not want to leave; they want a break. A seasonal business, a project on hold, a tight quarter. If cancel is the only option, they take it, and getting them back later costs a new checkout and often a discount. A pause keeps the subscription, the customer record and the payment method, and gives them an easy way back.

Paddle Billing supports pausing natively, through the API and through Paddle Retain’s cancellation flows. This guide explains how it works, what happens on resume, and how to offer it well. It sticks to Paddle’s documentation: pause a subscription, the pause subscription API reference, subscription pause or resume, the subscription.paused webhook, the changelog entries on resume billing options and pausing past-due subscriptions, and Cancellation Flows (all accessed November 2026).

How a pause works on Paddle

You pause a subscription with the pause subscription operation. The main options:

Field	What it does
`effective_from`	`next_billing_period` or `immediately`. For active subscriptions the default is `next_billing_period`.
`resume_at`	Optional date and time (RFC 3339) when the subscription should resume on its own
`on_resume`	How billing works when the subscription resumes (see below)

At the next billing period (the default)

Pausing at the next billing period is the gentle option. Paddle’s pause guide explains that it creates a scheduled change on the subscription saying it should pause on the next billing date. Until then, the subscription stays active and the customer keeps what they paid for.

You will see the scheduled change through subscription.updated, and subscription.paused once the pause takes effect, as described in subscription pause or resume.

Immediately

With immediately, the subscription pauses now. Use it when the customer explicitly asks to stop right away, or when your own logic needs it (for example, after a failed payment).

Resuming

A paused subscription can resume in two ways: automatically at resume_at if you set it, or when you call the resume operation.

What the customer pays on resume is controlled by on_resume, added in Paddle’s 2024 changelog:

start_new_billing_period (default): a new billing period starts and Paddle charges right away.
continue_billing_period: the subscription keeps its existing billing period. Paddle returns an error if you combine this with a resume date after the end of that period.

For most retention pauses, the default is easier to explain to customers: “your plan restarts on [date] and you’ll be charged then”. Use continue_billing_period for short pauses inside a period that the customer has already paid for.

Past-due subscriptions

Pausing interacts with failed payments in ways worth knowing:

Paddle’s docs say that while a subscription is past_due, you can still pause or cancel it, even though most other updates are blocked.
Paddle’s 2024 changelog says that when you pause a subscription, past-due renewal transactions are canceled automatically, to avoid charging for overlapping billing periods. When the paused subscription resumes, a new billing cycle starts.
Paddle returns an error if you try to continue the existing billing period for a past-due subscription. Use start_new_billing_period instead.

That makes a pause a reasonable end state for failed payments too. Paddle’s help article on retry cadence says you can choose to pause, cancel or leave a subscription past due when the recovery window ends.

Pausing and cancelling

One detail in Paddle’s Cancellation Flows docs: if a customer cancels an active subscription, it is scheduled to cancel at the next billing period, but a paused subscription is canceled immediately. Tell customers this in your pause confirmation, so “pause, then cancel later” does not surprise them.

Offering a pause with Paddle Retain

Paddle Retain’s Cancellation Flows run a short survey when a customer tries to cancel, then make an offer to stay. Paddle’s docs list pausing as one of the salvage options, scheduled for the next billing period, along with plan switches and a temporary discount when the customer declines the first offer. Cancel, pause and downgrade choices flow through to Paddle Billing.

Since January 2026, Paddle’s changelog says Cancellation Flows also appear when customers cancel in the Paddle customer portal, and from cancellation links in Paddle’s subscription emails. Without a configured flow, customers see a simple confirmation dialog. A later changelog entry adds that flows can be built and tested in sandbox through the customer portal.

For regions with one-click cancellation rules, Paddle’s 2024 changelog says a cancel link appears on every screen of the flow. Paddle detects those regions automatically.

How to offer a pause well

Match the offer to the reason. A pause answers temporary reasons: seasonality, a paused project, travel, a budget cycle. It does not answer “too expensive” or “missing features”. See pause vs discount retention offers.
Offer fixed lengths. One, two or three months, with resume_at set. Open-ended pauses tend to become silent cancellations.
Say what happens on resume. The date, the amount, and whether a new billing period starts.
Remind before resuming. Send an email a few days before resume_at with a link to extend or cancel. A surprise charge after a pause is a classic source of refund requests.
Keep cancel one click away. The pause is an offer, never a gate. See click to cancel rules.

Wiring it into your app

On subscription.updated with a scheduled pause, show the pause date in the account page.
On subscription.paused, switch the account to a paused state and decide what data stays visible.
On resume, restore access and log it.
In reports, count paused customers separately. A pause is not churn, but a pause that ends in cancellation should keep its original reason.

Test checklist

A pause at the next billing period keeps access until that date.
An immediate pause stops access right away.
resume_at resumes the subscription and charges as expected for your on_resume choice.
Pausing a past-due subscription cancels the overdue renewal.
Cancelling a paused subscription ends it immediately, and your app handles that.

Doing this with NoChurn

NoChurn’s cancel flow asks for a reason and offers a pause, a discount or a plan change based on it, with one-click cancel always visible. It runs hosted or headless through the API, so it fits apps where you do not use the Paddle portal. The subscription itself stays in Paddle, which remains the merchant of record. Cancel reasons then drive win-back emails at day 30, 60 and 90 and feed the churn score. See NoChurn + Paddle.