The Reference Docs Developer Hub

Welcome to the Reference Docs developer hub. You'll find comprehensive guides and documentation to help you start working with Reference Docs as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

Pause a Subscription

The ability to pause a subscription and effectively skip future subscription renewals

Occasionally, customers may want to pause their subscription instead of outright canceling their subscription. Having the option to pause instead of cancel is a great way to avoid voluntary churn and reduce marketing dollars to win customers back.

There are a lot of reasons why a customer may want stop their subscription billing

  • reducing costs
  • aren't using the service as frequently
  • going out of town
  • service provided is seasonal (e.g sports streaming service)

When subscribers request to pause their subscription, the subscription remains active until they reach the end of their current billing period, at which point the subscription will move into a paused state. Since most subscriptions are paid in advance, this allows the subscriber to use the service that they’ve already paid for. And your accounting or finance department doesn’t have to worry about prorating refunds, issuing credits for unused periods of time, or other billing complexities that result from mid-cycle changes.

How to Pause a Subscription

A subscription can be paused in the Admin Console or the API. See the API documentation for more information about how to use this feature in the API.

Key factors about this feature:

  • A subscription must be active and cannot be any of the following in order to pause:
    • future
    • in-trial
    • non-converted gift subscriptions
    • canceled
    • terminated
  • account cannot have any invoices past due if you want to pause a subscription.
  • you cannot specify a specific date to pause a subscription. It will always be based on the upcoming bill date of the subscription.
  • when a subscription is paused, you will not be able to log usage for usage based add-ons for the subscription unless it is resumed and returns back to an active state.
  • Change Bill Date of the subscription
    • if the subscription is paused, you will be unable to postpone a subscription unless you resume the subscription. This is due to the fact that the resume date is based on the renewal date. If you resume the subscription in order to postpone, keep in mind that resuming will bill the subscription for starting a new billing period.
    • if the subscription is scheduled to pause, changing the bill date will remove the pause. If you want to postpone the subscription, you should postpone before scheduling a pause.

Admin Console

You can pause a subscription from the admin console from the account of the customer and also from the specific subscription's details.

Pause from Subscription Details

To pause a subscription from the subscription details, open the subscription details of the subscription you would like to pause for the next renewal(s). Click on the Subscription Actions dropdown menu at the top right corner of the page, select Pause Subscription.

A Configure Pause Duration modal will open when clicking Pause Subscription button. There will be two fields in the modal.

The first field is called Pause Start Date, and is the date the pause will be initiated and the customer will not be charged. This date will always default to the subscription's bill date.

The second field in the modal is called "Number of Billing Cycles to Skip". This field is where you set the number of subscription bill dates (e.g invoicing events) to skip.

When you enter the number of billing cycles to skip, the description below the field should reflect the date range of the pause period. The value must be greater than 1.

Once you have configured the number of billing cycles to skip, click on Schedule Pause to confirm. You will see a yellow confirmation banner after scheduling the pause for the subscription.

Pause a subscription from the action dropdown menu

Pause a subscription from the action dropdown menu

Configure how long you would like the subscription to pause from this modal. The pause start date will always be based on the subscription's upcoming billing date.

Enter the number of billing cycles you want the subscription to skip and remain paused for.

Enter the number of billing cycles you want the subscription to skip and remain paused for.

Current Term Renewal Dates

While a subscription is paused, the original term renewal date of the subscription will not be updated (in the API this is represented as the current_term_ends_at timestamp). This is due to the fact that the scheduled pause can be canceled, the subscription could be resumed earlier, or the number of pause cycles could be updated. Any of the former events could potentially change the renewal date. Once a subscription is returned to active, the term renewal date will be updated.

To calculate the new renewal date while a subscription is paused, you will want to take original renewal date add the length of the pause period.

Alert banner will include details about the upcoming pause.

Alert banner will include details about the upcoming pause.

What if I want to pause a subscription indefinitely?

If you want to pause a subscription for a very long period of time, we suggest setting a very high value for the number of pause periods that you would like the subscription to be paused for. For example, a subscription with a monthly billing interval could be paused for 1200 periods - which would equate to 100 years. However, it is important to consider how your churn rates may not be accurately reflected if you have a high volume of subscriptions that are paused indefinitely.

Pause from Account

To pause a subscription from the account, find the account and the subscription on the account that you would like to pause for the next renewal(s). Click on the Options dropdown menu at the top right corner of the subscription, select Pause Subscription. Configure your pause duration and click Schedule pause to confirm.

Once successfully scheduled, you will see the pause details in a yellow alert banner within the subscription.

The subscription will remain active until it reaches its renewal date. At the next bill date, the subscription will move from active to paused and the customer will not be invoiced and charged for that subscription bill date.

Pausing a Subscription Example

Billy Joe is currently subscribed to a service that streams live professional football games online. Billy writes an email to the support team to pause his subscription for the next 4 months since the football season just ended. His subscription is set to bill on March 1st.

Once the support member has scheduled the pause for his subscription, Billy will not be invoiced and billed starting March 1st. On June 1st, after the paused subscription billing periods are completed, the subscription will resume and the Billy will be billed for his now active subscription.

Once you have configured the number of billing cycles to skip, click on Schedule Pause to confirm.

Cancel Pause

You can cancel a scheduled pause from the Account and the Subscription Details page.

Click on Cancel Pause by clicking on the Options menu of the subscription you'd like to cancel the pause for if you are canceling from the Account or by clicking on the Subscription Actions dropdown if you are on the Subscription Details page. Confirm by clicking Remove Scheduled Pause in the modal. If you're using the API, to cancel the scheduled pause, pass in a value of 0 as the number of billing cycles to skip.

Modify Pause Duration

You can modify the Number of Skipped Billing Cycles from the Account and the Subscription Details page.

From the Account, click on the Options menu of the subscription you'd like to edit and select Edit Pause.

From Subscription Details, you can click Edit Pause from the subscriptions dropdown menu, the action link within the yellow alert banner at the top, or from the action link located next to the subscription's Status.

Subscription Changes

If a subscription is paused or scheduled to pause and you want to make changes to the subscription, it's important to be aware of the Timing date of the changes you are making.

Immediate Changes

Making immediate changes to a subscription scheduled to pause will remove the scheduled pause. If the subscription is currently paused, immediate changes will resume the subscription back to an active state and start a new billing cycle. The resume date will become the start date of the subscription.

Example 1

Billy Joe's monthly subscription is scheduled to pause at his next renewal on Feb 1st. The subscription plan is modified to a lower price and the changes are plan effective Immediately. The subscription's scheduled pause is removed and will no longer pause at the next bill date.

Example 2

Billy Joe's monthly subscription is currently paused from February 1st - April 1st and will resume after two skipped billing cycles. On March 15th, he upgrades his subscription and the changes are made plan effective immediately. He is subsequently invoiced and charged for a new billing cycle for his upgraded subscription billing period of March 15th - April 15th and the subscription returns back to an active state. The subscription's bill date is now the 15th of each month.

At-Renewal Changes

If a subscription is scheduled to pause, subscription changes that are made plan effective At-renewal will go into effect after the subscription pause period ends or if the subscription is manually resumed.

Example 1

Billy Joe's monthly subscription is scheduled to pause on February 1st - April 1st. Billy decides that he wants to change is subscription plan at his next bill date. Since his subscription is scheduled to pause on February 1st, his next bill date will be on April 1st when his subscription resumes. This means that the subscription plan change will not occur until April 1st.

Example 2

Billy Joe's monthly subscription is currently paused from February 1st - April 1st. Billy decides that he wants to upgrade his subscription at his next subscription bill date. This means that on April 1st, after his pause period has ended, his subscription will be upgraded.

Resume Subscription

You can resume a paused subscription immediately from the Admin Console and the API. From the Admin Console, you can resume a paused subscription from the Account of the subscription and also in the Subscription Details.

Resuming a subscription will move the subscription from a pause state to active state. The customer will be invoiced immediately for a new billing cycle and payment method charged if the collection method is automatic. If you are using Calendar Billing alignment feature, the subscription's Bill Date will be respected and customer will receive prorated invoice that aligns to the Bill Date.

If you are resuming from Subscription Details, click on the Subscription Action dropdown menu. Clicking Resume will move the subscription from a pause state to active state. The customer will be invoiced immediately for a new billing cycle and payment method charged if the collection method is automatic.

If you are resuming from the Account, click Resume which is listed in the dropdown menu from the individual subscription's action menu.

Resume subscription from the dropdown menu

Resume subscription from the dropdown menu

Does Pausing Affect the Length of the Subscription Term?

Pausing a subscription will not impact the number of billing periods that the subscription has remaining. For example, let's look at a 12 monthly billing period term subscription that has already completed 2 billing periods (e.g 2 completed out 12 periods). If the subscription is paused for 3 billing periods, when it is resumed, it will still have 10 billing periods remaining and continue to bill for the next 10 months. Meaning, the number of paused billing periods does not get subtracted from the original total.

Closing an Account with Paused Subscriptions

If you are closing an account with subscriptions that are in a pause state, the paused subscriptions will be terminated immediately.

Canceling Paused Subscriptions

Unlike a regular active subscription where you have an option to refund the customer for any fixed fees paid up front see Expire Subscription, a paused subscription does not have a previous invoice to refund. Therefore, the only cancel action available for a paused subscription is to be terminated immediately.

Usage Based Add-Ons

If you are using usage based add-ons, usage will always be invoiced before a subscription transitions into a pause state. For example, if you are logging usage to a subscription scheduled to pause on April 2, 2018, an invoice will be generated that includes only usage based charges on April 2. While a subscription is currently paused, usage cannot be logged.

Coupons

When a subscription is paused, we will not pause the duration of a coupon applied to the subscription.

Coupons can also be a great tool to incentivize your customers to return to paying for your service. You can offer a promotional discount for the customer to upgrade their plan and resume their subscription. In this scenario, you would want to make an immediate subscription change to a new plan and apply the coupon to that change. This action will automatically resume the customer's subscription and return them back to a paying customer.

Example

Joe is subscribed to Silver Sports Package plan and currently has a subscription level coupon with a duration of 2 months, applied to it. The customer decides to pause their subscription for the next 4 months. This means that after 2 months pass while the subscription is paused, the coupon will expire. Thus, when the subscription resumes, the 2 month duration coupon, will not be applied to the invoice of that subscription.

Example

Joe is subscribed to Silver Sports Package plan has had their subscription paused for several months. As an incentive to get Joe back to using the sports streaming service, he's offered a discount coupon if he upgrades from Silver to the Platinum Package which includes more channels and access. Joe decides to take up the offer and upgrades his subscription using his coupon. In doing so, his subscription automatically resumes and he's now subscribed to Platinum

Email

Customers that have paused subscriptions may want to be notified when their subscription is about to resume and reactivate. Customers that have an upcoming subscription pause at their next renewal may also want to be notified that their subscription is going to be paused. Using the existing Renewal Reminder email, we've added two new subscription fields to that can be useful in the scenarios described earlier.

  • {{subscription_paused_at}} field can be used to display the date subscription will be paused
  • {{remaining_pause_cycles}} field can be used to display the number of subscription renewals that will be paused.

Webhook Notifications

Recurly's Pause Subscription feature can issue six notification events:

  • scheduled subscription pause
  • subscription pause canceled
  • subscription paused
  • subscription pause modified
  • paused subscription renewal
  • subscription resumed

See details of each pause notification in our Webhooks documentation.

Exports

To support this feature, there are two new columns that have been added to the Subscriptions Export. Those two columns are:

  • {{_paused_at}}: the timestamp of when the subscription was paused
  • {{remaining_pause_cycles}}: the number of remaining paused billing cycles

Analytics

For Recurly Analytics, subscriber count includes all open accounts with at least one active, paused, canceled subscription and includes subscriptions in trial. A paused subscription is treated the same as an active subscription in the calculations. Paused subscriptions are not considered as churned.

Hosted Account Management

Currently, a subscription cannot be paused or resumed by an end customer using Hosted Account Management. You can however, manually pause or resume a subscription via the API or Admin Console. The subscription's status in Hosted Account Management will display a state of pause if you do so.

If you would like to see future product functionality for pausing and resuming a subscription in our hosted pages solution, please write into support@recurly.com