Pause subscriptions: Things to consider
Review essential eligibility rules, plan type distinctions, and integration limitations before configuring subscription pauses in Recurly. Understand the technical differences between monthly and annual plan modifications, API versus Hosted Account Management (HAM) restrictions, and the overall impact on MRR and analytics tracking.
Retain • Pause Subscriptions
Things to consider
Eligibility rules, plan type differences, self-serve limitations, and caveats to understand before you configure anything.
Navigation Menu
Navigate Home
Things to consider
Eligibility requirements
Not every subscription can be paused. Before you configure pause, confirm your subscriptions meet these requirements — pausing an ineligible subscription will return an error.
Subscription must be active
Pause only works on active subscriptions. Expired, cancelled, failed, and trial subscriptions cannot be paused. If a subscriber is in dunning or past due, resolve that first.
Pauses apply to full billing cycles only
You can pause for one or more complete billing cycles — not partial periods. A one-cycle pause on a monthly plan suspends billing for one full month; on a quarterly plan, one full quarter.
Pause takes effect at the next billing date
Pause is scheduled, not immediate. When you apply a pause, it activates at the start of the subscriber's next billing cycle — not mid-cycle. The subscriber continues to have access and billing continues until then.
Usage-based add-ons cannot be tracked during pause
If your plan includes usage-based add-ons, those cannot be measured or billed during a pause period. Confirm your billing model before enabling pause — usage that occurs during a pause cannot be recovered.
Coupons continue to expire during a pause
Active coupon redemptions keep counting down during a pause period. A coupon with two months remaining when a subscriber pauses for three months will expire before billing resumes. Factor this in if your retention offer includes a coupon.
Monthly vs. annual plans — an important distinction
How pause behaves depends significantly on whether your subscribers are on monthly or annual billing. This is one of the most commonly misunderstood aspects of the feature.
| Monthly plans | Annual plans | |
| Recommended approach | Use the pause_subscription API endpoint directly | Use the update_subscription API to postpone the next_bill_date instead |
| What it does | Suspends billing for the number of monthly cycles you specify — e.g. 1 month, 3 months | Shifts the next annual billing date forward by the desired period, creating the same subscriber experience without a full annual cycle pause |
| Why the difference matters | Straightforward — pausing for 1 cycle = 1 month of suspended billing | Using pause_subscription on an annual plan pauses for one full annual cycle — effectively suspending billing for a year. That's almost never the intent. |
| MRR tracking | MRR stops contributing during the pause period | Postponement does not stop MRR tracking — monitor this outside Recurly if needed |
| Access & entitlements | Manage access through your entitlement system — Recurly does not control feature access | You must update your login or entitlement system to downgrade access during the postponement period |
If a subscriber six months into an annual plan requests a one-month break and you use pause_subscription with one billing cycle, it schedules a full one-year pause starting at their next annual renewal — not a one-month pause now. Use update_subscription to postpone the next bill date by the desired duration instead.
Self-serve limitations — know your integration
How pause is surfaced to subscribers depends on how your account management experience is built. This affects what you need to set up before pause is accessible to your customers.
Hosted Account Management (HAM) — no subscriber self-serve
If you use Recurly's Hosted Account Management pages, subscribers cannot pause or resume their own subscriptions from those pages. HAM will display a subscription's paused status, but the pause action itself must be triggered by your support team via the Recurly Admin Console, or through the API. If pause is a subscriber-facing retention tool for you, HAM requires a support-assisted workflow.
Custom portal via API — full self-serve available
If you manage subscriptions through a custom-built account portal using the Recurly API, pause and resume are available as subscriber-facing actions via the pause_subscription and resume_subscription endpoints. You control where and how the option is surfaced — in the cancellation flow, in account settings, or both.
Recurly Admin Console — available for support-assisted pauses
Any Recurly admin can pause or resume a subscription manually from the subscription's account page, regardless of your integration type. Navigate to the subscription details and use the Subscription Action dropdown to select Pause or Resume. This is the standard workflow for HAM merchants and support teams.
In regions subject to PSD2 and Strong Customer Authentication (SCA), resuming a subscription through the Recurly Admin Console may result in renewal failures. In these regions, the subscriber must initiate the resume directly — dashboard-triggered resumes bypass the required 3DS authentication step. Use the API with proper 3DS handling instead.
Other caveats to know
Subscription changes can cancel a scheduled pause
If you modify a paused or pause-scheduled subscription — for example, applying a plan change or updating billing terms — it can overwrite or cancel the scheduled pause. Review any pending pause before making other subscription changes.
Term renewal dates are not updated during pause
Recurly calculates the resume date from the original term plus the pause duration. A subscriber mid-term who pauses will resume at the correct billing date, but the term end date is not extended. Plan for this if your product grants access based on term end dates.
Paused subscriptions count as active in analytics
In Recurly Analytics, paused subscriptions are counted alongside active subscriptions — they are not treated as churned. They also contribute zero to MRR while paused since no invoices are generated. Keep this in mind when interpreting subscriber counts and MRR side by side.